Alcove

Alcove

HTTP API-based documentation server (always running). Auto-detects project by matching CWD against DOCS_ROOT folders.

Paths

All paths are resolved at runtime. ALCOVE_HOME env var overrides the default ~/.alcove.

Quick resolution from CLI:

alcove path              # show all resolved paths
alcove path --json       # JSON output (for scripts/AI)
alcove path docs         # docs root only
alcove path vaults       # vaults root only

Prerequisites

The alcove API server must be running. Check and start with:

alcove api status   # check if server is running
alcove api start    # start if not running

Resolve URL and token once at the start of every session:

eval $(alcove api env)
# sets ALCOVE_URL=http://127.0.0.1:<port>  (always)
# sets ALCOVE_TOKEN=<token>                (only if configured)

All commands below use $ALCOVE_URL. If $ALCOVE_TOKEN is set, add -H "Authorization: Bearer $ALCOVE_TOKEN" to every request.

Arguments

When to Use

Any question about project design, status, conventions, decisions, env config, tech debt, code structure, or doc health. Check alcove before answering, not after.

Document Routing

IMPORTANT: This table maps question types to document filenames. When users ask these questions, SEARCH first — do not directly fetch files.

Workflow: Search → read results. Never fetch PRD.md, ARCHITECTURE.md etc. directly based on this table alone.

API Reference

Search & Discovery

Query Construction

Extract 2-3 key terms from the question. Avoid natural language filler.

Default: 1-2 keywords from the question.

Use the search endpoint. Project is auto-detected from CWD.

# Search current project (default)
curl -s '$ALCOVE_URL/search?q=QUERY'

# Search with options
curl -s '$ALCOVE_URL/search?q=QUERY&limit=10&mode=hybrid'

# Search a specific project
curl -s '$ALCOVE_URL/search?q=QUERY&project=PROJ'

# Search across all projects
curl -s '$ALCOVE_URL/search?q=QUERY&limit=20'

# POST search (JSON body)
curl -s -X POST $ALCOVE_URL/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"q": "QUERY", "limit": 10, "project": "proj", "mode": "hybrid"}'

Response: {"query": "...", "results": [...], "mode": "...", "truncated": false}

Project Operations

# List projects
curl -s $ALCOVE_URL/projects

# Init project
curl -s -X POST $ALCOVE_URL/projects \
  -H 'Content-Type: application/json' \
  -d '{"project_name": "myproj", "project_path": "/abs/path"}'

# Project docs overview (with sizes and classification)
curl -s $ALCOVE_URL/projects/PROJECT/docs

# Audit doc health
curl -s $ALCOVE_URL/projects/PROJECT/audit

# Validate against policy.toml
curl -s $ALCOVE_URL/projects/PROJECT/validate

# Configure project settings
curl -s -X PUT $ALCOVE_URL/projects/PROJECT/config \
  -H 'Content-Type: application/json' \
  -d '{"core_files": ["PRD.md", "ARCHITECTURE.md"]}'

# Read a doc file
curl -s '$ALCOVE_URL/docs/PRD.md?project=PROJECT'
curl -s '$ALCOVE_URL/docs/reports/weekly.md?project=PROJECT&offset=0&limit=2000'

# Index code structure
curl -s -X POST $ALCOVE_URL/index-code \
  -H 'Content-Type: application/json' \
  -d '{"source_path": "/abs/path/src", "language": "rust", "project": "PROJECT"}'

Index & Maintenance

# Update index — incremental (changed/added/deleted files only), all projects
curl -s -X POST $ALCOVE_URL/index
# ↑ DEFAULT for "make new docs searchable" or "rebuild index"

# Update index — single project only
curl -s -X POST $ALCOVE_URL/projects/PROJECT/index
# ↑ ONLY when explicitly targeting a specific project

# Check changed files since last index
curl -s '$ALCOVE_URL/changes?auto_rebuild=true'

# Lint docs
curl -s '$ALCOVE_URL/lint?project=PROJECT'

Rule: Default to /index (global). Use /projects/{name}/index only when task specifies a single project.

Vault Operations

# List vaults
curl -s $ALCOVE_URL/vaults

# Search vaults
curl -s '$ALCOVE_URL/vaults/search?q=QUERY&vault=*&limit=20'

# Backup vault
curl -s -X POST $ALCOVE_URL/vaults/backup \
  -H 'Content-Type: application/json' \
  -d '{"vault_name": "myvault"}'

# Promote document into doc-repo
curl -s -X POST $ALCOVE_URL/promote \
  -H 'Content-Type: application/json' \
  -d '{"source": "/abs/path/notes.md", "project": "PROJECT", "copy": true}'

Agent Memory (#37)

Durable cross-session memory backed by the memory vault. Store facts/decisions/preferences; recall them before acting. valid_until (ISO 8601) makes time-sensitive facts drop out of recall automatically.

# Store a memory (title defaults to first line)
curl -s -X POST $ALCOVE_URL/memory/store \
  -H 'Content-Type: application/json' \
  -d '{"content": "user prefers turbofish syntax", "project": "alcove", "valid_until": "2027-01-01T00:00:00Z"}'

# Recall memories (hybrid BM25 + vector)
curl -s '$ALCOVE_URL/memory/recall?q= syntax  preference&limit=10'

Memory files live in ~/.alcove/vaults/memory/ — editable/removable directly; changes are picked up on next store (which re-indexes).

Doc Graph (backlinks/related) — requires doc-graph feature

# Docs linking TO a file (backlinks)
curl -s '$ALCOVE_URL/docs/backlinks?file=PROJECT/PRD.md'

# Docs a file links TO (related)
curl -s '$ALCOVE_URL/docs/related?file=PROJECT/PRD.md'

# Stamp last_verified=now on a doc
curl -s -X POST '$ALCOVE_URL/docs/verify?file=PROJECT/PRD.md'

# Count docs excluded from recall by expiry
curl -s $ALCOVE_URL/docs/expired

Expired docs (valid_until in the past) are excluded from backlinks/related recall in both directions.

MCP Proxy (Legacy)

The JSON-RPC proxy remains available for MCP clients:

curl -s -X POST $ALCOVE_URL/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{}}}'

Health Check

curl -s $ALCOVE_URL/health
# → {"status": "ok", "version": "x.y.z", "docs_root_configured": true, "projects": N}

Rules

Scope

Default: current project. Ambiguous → ask. Global only on explicit request.

Before writing code

1. CONVENTIONS.md → project-specific rules
2. CODE_INDEX.md → compact module/type/function overview (avoids reading dozens of source files)
3. For research/reference material → search vaults via GET /vaults/search?q=...

Answering questions

Never answer from memory. Call GET /projects/{name}/docs → GET /docs/{path}?project=name for the relevant file → summarize. Do not dump full files unless asked.

Doc status disambiguation

Ambiguous → call audit_project (broadest).

Acting on audit results

• alcove → project repo: OK for public-facing docs derived from internal content
• project repo → alcove: OK to restructure reference materials
• Internal docs → project repo: NEVER expose PRD/ARCHITECTURE/etc.
• Always confirm before moving/deleting files
• Re-run validate + lint after cleanup

Promoting notes

Path provided → act immediately: POST /promote with the source path. No matching project → inbox/. Then POST /index.

After development

Proactively capture at natural stopping points:

• Architecture change → ARCHITECTURE.md
• Decision rationale → DECISIONS.md
• Bug/workaround → DEBT.md
• Coding pattern → CONVENTIONS.md
• Env var → SECRETS_MAP.md
• Progress → PROGRESS.md

Read → append with date → POST /index.