context-keeper CLAUDE.md

Context Keeper MCP Server

Context Keeper maintains project memory across Claude conversations: architectural decisions, pipeline flows, and constraints that must not be forgotten or violated.

Project Resolution

Context Keeper stores data in a .context/ directory inside a project. The server resolves the project directory in this order:

1. CONTEXT_KEEPER_PROJECT env var (explicit opt-in — trusted)
2. The Xylem session pointer ~/.xylem/active_project.json (override with XYLEM_ACTIVE_PROJECT_FILE), written by the Xylem SessionStart hook. Also an explicit opt-in: it exists so a persistent server follows the session's project rather than the directory it happened to be launched from, so it outranks cwd discovery.
3. cwd, but only if it already contains a .context/ directory
4. Walk parent dirs from cwd, returning the first ancestor that already contains a .context/ (git-style discovery — so launching from a subdirectory of your project still resolves correctly)
5. Otherwise: refuse. record_*, update_entry, deprecate_entry, and prune_stale all return an "unresolved project" error.

Steps 3 and 4 only resolve to directories that already contain .context/. The server never creates one implicitly, so you will never silently create a stray .context/ in the wrong directory. The footgun from earlier versions — where Claude Code was launched from a parent directory and polluted it — is fixed at the code level.

All 14 tools accept project_dir for explicit cross-project targeting. When cwd doesn't resolve, pass project_dir to any tool — including record_*.

Still good practice:

• When recording to a non-obvious project, confirm with the user which project you're targeting before calling record_*.

Capture Loop

Context Keeper has two halves:

1. Retrieval (session start): The SessionStart hook injects the compaction report and project summary directly into context (it runs the handlers itself and prints their output). Retrieval is automatic and unskippable — you do not need to call the tools to be oriented on what's already recorded. get_compaction_report / get_project_summary remain callable on demand.