claude-memory-compiler: Turning Claude Code Sessions into a Markdown Knowledge Base

The problem: Claude Code forgets everything when the session ends

Claude Code sessions are disposable by default. You resolve an architectural question on Monday, the context window compacts or the session ends, and on Tuesday the same question gets asked again. The repository does not record why a decision was made, only what the code looks like afterward. claude-memory-compiler targets that gap. It is built for a single developer or a small team working repeatedly in the same codebase, where the useful residue of a session is not the code that was written (git already tracks that) but the reasoning: which approach was rejected, which library caused trouble, which configuration flag mattered. The README frames the raw input as your own conversations with Claude Code, adapted from Karpathy's LLM Knowledge Base architecture, which clipped web articles instead. The audience is narrow on purpose. This is a personal-scale tool, and the README says so when it argues that retrieval without embeddings works up to roughly 500 articles.

The pipeline: hooks to daily logs to concept articles to an injected index

The data flow is stated as a single line in the README: conversation, then SessionEnd and PreCompact hooks, then flush.py, then a daily log at daily/YYYY-MM-DD.md, then compile.py, then knowledge/concepts/, knowledge/connections/ and knowledge/qa/, then a SessionStart hook that injects the index into the next session. Two capture points matter. SessionEnd fires when a session closes normally. PreCompact fires before auto-compaction, which is the safety net for long sessions that would otherwise lose their early turns before the end hook ever runs. flush.py does not do keyword extraction. It calls the Claude Agent SDK and asks a model to decide what is worth saving, then appends the result to the day's log. Compilation is separate and batched: after 6 PM local time, the next flush triggers end-of-day compilation automatically, and compile.py can also be run by hand. The output is not a flat dump. Articles are organized by concept, with cross-references between them, and the three directories suggest a split between concept articles, relationship articles, and question-and-answer entries. Only the index is injected into a new session, not the articles themselves. That is the actual retrieval mechanism, and it is worth being precise about it: the model reads a structured index, decides which articles are relevant, and presumably reads those on demand.

Why the project refuses to use a vector database

The README's argument is quoted from Karpathy: at personal scale, between 50 and 500 articles, an LLM reading a structured index.md outperforms vector similarity, because the model understands what you are actually asking while cosine similarity only finds similar words. The README then names its own boundary condition, around 2,000 or more articles, where the index exceeds the context window and RAG becomes necessary. This is a real design position rather than a shortcut, and it has consequences. There is no embedding model to host, no vector store to keep in sync, no chunking strategy to tune, and no separate service that can drift out of date relative to the markdown. Everything is inspectable in a text editor. The cost is that retrieval quality depends entirely on how well compile.py writes the index, and that dependency is invisible until it fails. If the index omits an article, query.py will not find it. There is no fallback similarity search to catch what the index missed.

Getting it running: uv sync, settings.json, and five scripts

The README's quick start is written for an AI coding agent rather than a human, which is itself a signal about the intended workflow. It instructs the agent to clone the repository into the project, run uv sync to install dependencies, copy .claude/settings.json into the project or merge the hooks into an existing settings file, and let the hooks activate the next time Claude Code opens. The technical detail lives in AGENTS.md, which the README describes as a complete reference covering article formats, hook architecture, script internals, cross-platform details, costs, and customization. That file is the one to read before changing anything, because the hook entries in settings.json are the part most likely to break on a given machine. Five commands cover day-to-day use: uv run python scripts/compile.py to compile new daily logs, uv run python scripts/query.py "question" to ask the knowledge base, the same query with --file-back to save the answer back into the base, uv run python scripts/lint.py for all seven health checks, and uv run python scripts/lint.py --structural-only for what the README calls the free structural checks. That last flag implies the full lint pass costs something, most likely model calls. The README does not say what the seven checks cost or how long they take, so treat that as unverified.

The lint script is the project's most underdescribed component

lint.py runs seven health checks, and the README names four of them: broken links, orphans, contradictions, and staleness. The remaining three are not listed in the README; presumably AGENTS.md covers them. The four that are named tell you what the authors expect to go wrong. Broken links means articles reference each other by name and those names drift. Orphans means compiled articles that nothing links to, which in an index-driven retrieval system means articles that will never be found. Contradictions means the compiler detected two articles disagreeing, which is the interesting case: a knowledge base built from months of sessions will accumulate a decision from March that a later session reversed, and nothing in the pipeline automatically reconciles them. Staleness means age-based flagging. The existence of a contradiction check implies the project does not resolve contradictions during compilation, only reports them. That is a defensible choice, since automatic reconciliation would silently rewrite history, but it means the base degrades unless someone reads the lint output. The --structural-only flag suggests the checks split into mechanical ones and ones that need a model, and the README's word "free" implies the mechanical set runs without cost.

The licence is the first thing to check, and the README does not say

The repository metadata carries no licence identifier, and no LICENSE file is mentioned in the supplied material. For a tool that runs inside your editor and reads your conversation transcripts, that is not a minor omission. Without a stated licence, the default position is that no rights are granted beyond what the hosting platform's terms allow, which matters if you intend to use this at work or redistribute a modified copy. The README does address one cost question directly: it states that Anthropic has clarified personal use of the Claude Agent SDK is covered under an existing Claude subscription (Max, Team, or Enterprise), with no separate API credits needed, and contrasts this with OpenClaw, which the README says requires API billing for its memory flush. That is a claim about Anthropic's policy, not about this project, and it is worth confirming against current Anthropic documentation rather than taking a README's word for it. The practical consequence if the claim holds is that the marginal cost of running flush and compile is your subscription, not a metered bill, which changes how often you can afford to run the full lint pass. If it does not hold, every session flush and every compilation is a billed model call, and the economics of running this on every session change substantially.

Where it breaks: multi-machine use, index growth, and the wrong-tool case

Three limitations are visible from the material. First, the knowledge base is local markdown under daily/ and knowledge/. Nothing in the described pipeline merges two divergent copies, so if you work on a laptop and a desktop, you are either syncing the directory yourself or accepting two separate bases. Second, the index is the retrieval ceiling. The README puts the RAG threshold around 2,000 articles, but the practical threshold for a specific user is lower and depends on how verbose compile.py is when it writes index entries; a daily Claude Code user could plausibly approach a few hundred articles within a year, which is still inside the stated range but no longer at the low end. Third, the tool is the wrong choice if your knowledge is not in Claude Code sessions. If your decisions live in pull request reviews, Slack threads, or design documents, this pipeline captures none of it, and you would be better served by a general retrieval setup over those sources. A concrete alternative is a conventional RAG stack: chunk your session transcripts, embed them, and query a vector store. That approach handles thousands of documents without an index file and does not depend on a compiler writing good summaries. The difference in approach is the locus of intelligence. claude-memory-compiler puts a model at write time, deciding what to keep and how to organize it, and keeps retrieval mechanical. RAG puts nothing at write time and a model at read time, over raw chunks. The first gives you a curated base that can be read by a human; the second gives you recall over everything you fed it, including the parts that did not matter.

Maintenance cost and who this is actually for

The maintenance surface is small: five Python scripts, a hooks configuration, and a directory of markdown. There are no releases listed for the repository, so upgrades mean pulling from main rather than tracking versioned tags, which is worth knowing before you build habits around the current script interfaces. The scripts are invoked through uv, so dependency resolution is pinned by the project's own lockfile after uv sync. The real recurring cost is not code maintenance but attention: reading lint output, noticing contradictions between an old decision and a new one, and occasionally pruning articles that no longer reflect how the codebase works. The compile step is automatic after 6 PM, but nothing in the described pipeline automatically deletes or rewrites a concept article that later sessions have invalidated. That is the honest trade. You get a knowledge base that is a set of plain markdown files you can read, diff, and edit by hand, and in exchange you own the curation that a hosted memory product would hide from you. For a solo developer who already lives in Claude Code and wants session reasoning to persist across context resets, that trade is reasonable. For a team that needs a shared, always-current knowledge store with a clear licence and a merge story, this is not that tool yet.

Editorial conclusion

Adopt claude-memory-compiler if you run Claude Code daily on one or a few repositories and you want session knowledge to survive context resets without standing up a vector store. Do not adopt it if you need a documented licence before shipping it internally, if you work across many machines and expect the knowledge base to merge itself, or if you already have a retrieval stack you trust. Before committing, check three things: whether the repository carries a LICENSE file, what the hook entries in .claude/settings.json actually invoke on your operating system, and how large index.md grows after a month of your own sessions, since that file is the retrieval mechanism and its size is the ceiling on the whole approach.

Official sources

1. coleam00/claude-memory-compiler on GitHub
2. Issues
3. README