pagelore

Durable project memory for AI coding agents — Claude Code, Codex, Cursor, Gemini CLI. Decisions, contracts and bug post-mortems live as markdown pages in your repository, searched with BM25F from a command line or an MCP server, and every write is validated before it lands. No server, no database to run, no API key, no hooks; the runtime is the Python 3.9+ standard library.

Works with: Claude Code · Codex CLI · Cursor · Gemini CLI · anything that can run a shell command or an MCP stdio server.

Why

Agents re-derive the same context every session and confidently restate decisions that were reversed months ago. A memory store fixes that only if it is cheap to write, cheap to read, and survives switching tools. Plain markdown in git satisfies all three: the store is a .memory/ directory of .md files — greppable, diffable, reviewable in a pull request, readable by any agent or person.

• Search that ranks. BM25F over title and body; a SQLite FTS5 index kept as a disposable cache outside the store, and an in-process ranker when the index cannot be used. Measured against grep, embeddings and the closest competitor.
• Writes are refused, not requested. A page with no sources, a source that does not exist, or too little body is rejected with a FIX: line the agent acts on.
• Reversals stay honest. --supersedes stamps the old page, halves its score and marks it ⚠ superseded by <slug> in every result.
• One instruction line connects an agent. lore init writes it (or registers the MCP server) and lore doctor catches the setups that fail silently.

Install

pipx install pagelore && lore init && lore doctor     # or: npm install -g pagelore

lore init shows the exact change and asks before writing; its default connects nothing. lore doctor says what is connected and what is broken. Other routes (pip, uv, from source), upgrading and removal: installation.

Quick start

Connect Claude Code in this repository only, with the instruction file:

lore init --agent claude --scope project --yes

Your agent now searches before it answers and writes after meaningful work. The same commands by hand:

lore search "terminal freeze webgl context lost"     # ranked hits: slug — title — what matched
lore search --touching src/terminal/renderer.ts      # pages written against this file, first
lore show webgl-context-loss                         # one page, by the slug a search printed
lore write --slug webgl-context-loss --title "xterm WebGL context loss on display sleep" \
  --kind bug --source src/terminal/renderer.ts --body - <<'PMEOF'
## Cause

The WebGL renderer loses its context when the display sleeps; what a future
agent could not reconstruct from the code goes here.
PMEOF
lore list                                            # every page, newest first
lore stats                                           # writes, refusals, searches that found nothing

Or as MCP tools, memory_search and memory_write, in the agent's tool list:

lore init --agent claude --via mcp --scope project --yes   # writes .mcp.json

How it works

  agent (Claude Code, Codex, Cursor, Gemini CLI, …)
     │ reads one @-line or pasted block every turn          ~/.project-memory/AGENT.md
     │
     ├── lore search / show / write   (shell)  ─┐
     └── lore mcp  memory_search / memory_write ─┤  same functions, same gate
                                                 ▼
                          .memory/*.md   ← the source of truth, in your repo
                          FTS5 index     ← a cache in ~/.cache, rebuilt on demand

The instruction block lives in one file, ~/.project-memory/AGENT.md, refreshed by every lore command; each agent's configuration carries one line pointing at it, so an upgrade reaches every agent without editing anything. Measured on Claude Code: with the line the agent searched before answering 15 times out of 15, without it never.

Documentation

• Installation — pipx, pip, uv, npm, from source; upgrading, uninstalling, 0.3.x
• Connecting agents — every agent at once, one project, one specific agent
• MCP server — lore mcp, its two tools, per-client registration
• CLI reference — every command and flag, exit codes, the write gate, the log
• Configuration — environment variables and files
• Troubleshooting — what each lore doctor line means
• FAQ
• Page format · Retrieval · Measurements
• Contributing · Security · Changelog

License

MIT — see LICENSE.