Local memory

Markdown-only local agent memory under .ai/memory with candidate capture hooks (ADR-024).

Local memory gives coding agents durable, repo-local project knowledge as Markdown under .ai/memory/, with host hooks that capture candidates into a gitignored inbox. Agents promote confirmed facts with capture skills and navigate via index.md routers — no local memory daemon and no ctxpipe-memory MCP.

Use it when you want agents to remember architecture decisions, conventions, glossary terms, and curated notes across chats and tools, while keeping useful memory reviewable in Git.

Markdown-only (ADR-024)

Install with npx ctxpipe memory init (or npx ctxpipe init --memory). Hooks write candidates only; durable ADRs and lessons are promoted by the agent.

How it fits with ctx| MCP

Surface	What it does
`ctxpipe` (remote MCP)	Organization-scoped context from repositories, connectors, the knowledge graph, and `ctx_advisor`.
Local memory (this page)	Repo-scoped Markdown under `.ai/memory/` plus host capture hooks — not an MCP server.

You can use local memory alone (memory init) or next to the remote ctxpipe MCP (init --memory).

Install

npx ctxpipe memory init --agents cursor,claude --scope repo --non-interactive

Or with the main wizard (includes optional remote MCP):

npx ctxpipe init --org acme --agents cursor,claude --scope repo --memory --non-interactive

Init seeds .ai/memory/ (indexes, lessons, decisions, PRDs, sessions, events), installs the ai-memory rule and capture / memory-search skills, and wires capture for the agents you select:

Cursor, Claude, Codex — host lifecycle hooks call memory capture observe|finalize.
OpenCode, VS Code Copilot — instruction files that tell the agent to run the same capture CLI (those hosts lack equivalent Stop-hook wiring).

Layout

.ai/memory/
  README.md
  index.md
  lessons-learned.md
  glossary.md
  product-context.md
  decisions/index.md + ADR-*.md
  PRDs/
  sessions/
  events/          # gitignored candidate inbox

Capture and promote

Capture CLI (observe / finalize) runs from host hooks or agent instructions (fail-open).
Candidates land in .ai/memory/events/ (not committed).
Stop/summary surfaces a short promotion list — capture never writes durable ADRs.
Agents write durable Markdown with capture-adr, capture-lesson, capture-glossary, or capture-decision, update the matching index.md, then run memory capture promote|dismiss <id> so candidates leave the surfaced set.

Recall

No embeddings search process. Prefer index.md routers, then:

rg -i "keyword" .ai/memory --glob '*.md' --glob '!events/**'

See the installed memory-search skill for the full procedure.

Upgrade from older local memory

Re-run npx ctxpipe memory init. Init strips retired ctxpipe-memory MCP entries (including Codex config.toml), ConKeeper memory skills, replaces AgentMemory-era .ai/memory/README.md when detected, refreshes managed capture / memory-search skills, and migrates patterns.md into lessons-learned.md when present.

CLI: npx ctxpipe memory status|doctor
Capture skills and the memory-search skill are installed into your agent skills directory on init.