Alcove

About The Project

Alcove keeps personal knowledge work inspectable, portable, and agent-friendly. It stores user data in local Markdown, YAML, and JSON, while providing governed CLI/MCP write paths and broad AI-led read paths.

The core model:

Read  -> search candidates, inspect local evidence, synthesize with context
Write -> route through Alcove CLI/MCP contracts, update indexes, validate

Data ownership is explicit:

• ~/.alcove stores global memory, indexes, service state, dashboard snapshots, radars, publishers, automations, and usage rollups.

• Managed knowledge bases live wherever the user chooses and are registered under ~/.alcove/knowledge-bases/.

• Mounts and connectors index external sources without taking ownership of the original data.

• The dashboard and Apple Notes publisher are derived views, not source-of-truth stores.

Related MCP server: suasor

Features

• Managed knowledge bases — inbox capture, manual drafts, archive, OKF notes, taxonomy, validation, and indexed retrieval.

• Global personal memory — pins, prompts, tasks, ideas, routines, and local project aliases under Alcove Home.

• External knowledge sources — read-only mounts plus Apple Notes, GitHub Stars, and Chrome Bookmarks connectors.

• Agent entry modes — Hub workspace, lightweight global MCP, managed-KB workspace, business workspace OKF, and local service runtime.

• Configurable radars and monitors — scheduled information reports, watched feeds/pages, blog discovery, optional capture, optional AI summary, and Telegram/Feishu/tmux-claude-bot notification sinks.

• Local dashboard — browser-facing workbench generated from local data.

• External readable mirrors — Apple Notes publishing for selected personal memory views.

• Health and repair — cross-module data checks, OKF validation, safe index rebuilds, deep local maintenance, and agent smoke/eval hooks.

Built With

• Language / runtime — Python 3.12+

• Packaging / environment — uv

• CLI / MCP — argparse, FastMCP

• Data formats — Markdown + YAML frontmatter, JSON, YAML

• Quality gates — Ruff, mypy, pytest, pytest-cov, pip-audit, gitleaks

Architecture

Codex / Claude Code / CLI / MCP / Dashboard
                    │
                    ▼
             Alcove Application
                    │
   ┌────────────────┼────────────────┐
   │                │                │
Managed KBs   Global Memory   External Indexes
 inbox          pins           mounts
 archive        prompts        connectors
 OKF notes      tasks          fetch refs
 validation     projects       OKF mirrors
   │                │                │
   └────────────────┼────────────────┘
                    ▼
       Global OKF Catalog / Search Rows
                    │
        Dashboard / Publishers / Service

Key design rules:

• Reads are broad. Agents can search, inspect OKF files, follow source refs, fetch connector details, and read mounted evidence.

• Writes are narrow. Durable mutations should go through Alcove CLI/MCP so frontmatter, provenance, indexes, activity logs, and health checks remain consistent.

• Derived files are disposable. Rebuild dashboard snapshots, usage rollups, JSON indexes, and OKF catalogs from source-of-truth data.

See docs/architecture.md and docs/read-write-model.md for the full model.

Getting Started

Installation

uv tool install git+https://github.com/OctopusGarage/alcove.git
alcove --version

For local development:

git clone https://github.com/OctopusGarage/alcove.git
cd alcove
uv sync
uv run alcove --version
uv tool install --force -e .

First Setup

alcove home init
alcove kb add research_notes /path/to/research_notes
alcove hub init ~/AlcoveHub --default-kb research_notes
alcove hub install ~/AlcoveHub --default-kb research_notes
alcove workspace init family --default-kb research_notes
alcove workspace okf init family --json
alcove global install --default-kb research_notes
alcove kb install research_notes

Entry profiles:

Development link mode keeps Alcove-owned skills and commands symlinked to the repository templates:

alcove hub install ~/AlcoveHub --default-kb research_notes --link
alcove workspace install family --link
alcove kb install research_notes --link

Core Workflows

Managed KB

alcove inbox --kb research_notes peek
alcove inbox --kb research_notes manual-add "Manual Thought" \
  --content "Copied note text" \
  --source "chat://manual"
alcove knowledge --kb research_notes note-source \
  --platform web \
  --title "Example" \
  --topic agent-engineering/agent-harness \
  --summary "Summary"
alcove search "Example" --kb research_notes

Global Memory

alcove pin add "Useful Pattern" --description "Short reusable note" --tag reference
alcove prompt propose "Code Review Lens" --content "Review the diff for regressions..." --tag review
alcove prompt save --proposal-id <proposal-id>
alcove prompt recommend "review a dashboard regression before shipping"
alcove prompt compose "review a dashboard regression before shipping"
alcove prompt audit --json
alcove task add "Wire MCP search" --priority high --tag mcp
alcove project add alcove /path/to/alcove --note "Personal information core"

External Indexes

alcove mount add /path/to/repos --name repos --type local-folder --profile docs --tag repos
alcove mount scan repos --dry-run --json
alcove mount scan repos --json
alcove connector github-stars import-url "https://github.com/octocat?tab=stars" --json
alcove connector chrome-bookmarks import-local --tag bookmarks --json
alcove connector apple-notes import-local --tag apple-notes --json
alcove connector status --json

Mount profiles keep local repository indexes focused. Use docs for README and documentation-heavy repositories, site for blog/site content, notes for personal Markdown folders, and capture-bundles for Clipsmith-style captured article folders. Add --include and --exclude when a specific mount needs custom rules.

Radars, Watchers, and Blogs

alcove radar preset list --json
alcove radar init tech-news --from-preset tech-news --json
alcove radar run tech-news --force --ai --notify --json
alcove watch add "Example Blog" https://example.com/feed.xml --kind rss --kb research_notes
alcove blog check --stale --json

Dashboard and Publishers

alcove dashboard --home ~/.alcove build
alcove serve --dashboard --home ~/.alcove --port 8765
alcove global install --default-kb research_notes
alcove publish init apple-notes --root-folder "iCloud/Alcove" --json
alcove publish run apple-notes --json

alcove global install initializes the default Apple Notes publisher and installs the scheduler LaunchAgent so due publisher runs happen through background alcove service tick. Alcove writes to mirrored sources mark the publisher dirty, so the next scheduler tick can re-export changed Notes before the normal 24-hour TTL. Use alcove publish run apple-notes when an immediate manual sync is needed.

Operations

Run a normal health check:

alcove health --home ~/.alcove --json
alcove health --home ~/.alcove --kb research_notes --fix --json

Run a local full-maintenance pass:

alcove health --home ~/.alcove --fix --deep --json

--deep rescans mounts, rebuilds usage rollups, rebuilds the dashboard snapshot, and rebuilds the global OKF catalog. Connector refresh remains explicit:

alcove health --home ~/.alcove --fix --deep --refresh-stale-connectors --json

Serve deterministic background work through launchd:

alcove service install --dashboard --scheduler --load
alcove service status
alcove service tick --json

Back up managed KB roots and ~/.alcove outside the Alcove runtime. Recommended tools:

• scheduled Git sync: https://github.com/OctopusGarage/git-auto-sync

• optional Git encryption: https://github.com/AGWA/git-crypt

Documentation

• Documentation Index

• Usage Guide

• Entry Modes

• Agent Workspaces

• Architecture

• Modules

• OKF Profile

• Read/Write Model

• Data and Backup

• Coverage Setup

• Smoke and Agent Eval

Development

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
scripts/verify/check.sh

Coverage is generated as coverage.xml by pytest and uploaded in CI from the Ubuntu matrix job. See docs/coverage.md for Codecov setup.

License

Distributed under the MIT License. See LICENSE.