Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coleam00/claude-memory-compiler/llms.txt

Use this file to discover all available pages before exploring further.

Claude Memory Compiler is modeled on a software compiler. Your conversations are source code: raw, unstructured, full of important decisions buried between tool calls. The LLM is the compiler: it reads the source, extracts what matters, and produces an organized, cross-referenced knowledge base you can query and that Claude reads automatically at the start of every session. You write code; the system handles the rest.

​
The full pipeline

Conversation -> SessionEnd/PreCompact hooks -> flush.py extracts knowledge
    -> daily/YYYY-MM-DD.md -> compile.py -> knowledge/concepts/, connections/, qa/
        -> SessionStart hook injects index into next session -> cycle repeats
Every piece of the pipeline runs automatically. You do not need to trigger flushes, schedule compiles, or curate articles. The only manual step is running compile.py before 6 PM local time — after that, it runs itself.

​
The three layers

daily/ — Conversation logs

The raw source material. Each session end appends a structured entry to today’s daily/YYYY-MM-DD.md file. These files are immutable once written — append-only, never edited. They are the ground truth your knowledge base compiles from.

knowledge/ — Compiled articles

The LLM-owned output. Concept articles in knowledge/concepts/, cross-cutting insights in knowledge/connections/, and filed query answers in knowledge/qa/. The master catalog at knowledge/index.md is the retrieval mechanism — one row per article, one-line summary, injected into every session.

AGENTS.md — The compiler spec

The schema that tells the LLM how to compile and maintain the knowledge base. It defines article formats, wikilink conventions, writing style, and every operation the LLM performs. Changing AGENTS.md changes how the compiler behaves — without touching any code.

scripts/ — The CLI tools

compile.py runs the compile step. query.py answers questions using index-guided retrieval. lint.py runs seven health checks. flush.py is the background extraction agent. All are invoked with uv run python scripts/<name>.py.

​
Why index-guided retrieval instead of RAG

At personal knowledge base scale — typically 50 to 500 articles — the LLM reading a structured knowledge/index.md outperforms vector similarity search. The index is a markdown table: one row per article, with a one-line summary. The LLM reads the whole table, understands what you are actually asking, and selects the 3–10 most relevant articles to read in full before synthesizing an answer. RAG finds words that are similar to your query. The LLM finds concepts that are relevant to your question. At this scale, the distinction matters. Vector databases become necessary only when the index grows past roughly 2,000 articles and exceeds the context window.

​
The background flush process

When a session ends, session-end.py extracts the last 30 turns of the conversation transcript (up to 15,000 characters) into a temporary .md file, then immediately exits. The hook itself makes no API calls — it completes in under 10 seconds. flush.py is then spawned as a background process via subprocess.Popen. On Windows, the hooks use CREATE_NO_WINDOW to suppress a console flash; on Mac and Linux no special flag is set. flush.py itself then calls start_new_session=True (Mac/Linux) or CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS (Windows) when it in turn spawns compile.py, fully detaching the compile subprocess. flush.py then:
  1. Sets CLAUDE_INVOKED_BY=memory_flush to prevent recursive hook firing
  2. Checks deduplication — skips if the same session was flushed within 60 seconds
  3. Calls the Claude Agent SDK with allowed_tools=[] and max_turns=2 — no tool use, just text extraction
  4. Claude decides what is worth saving and returns a structured entry or FLUSH_OK
  5. Appends the result to daily/YYYY-MM-DD.md
  6. Cleans up the temporary context file
  7. If it is past 6 PM local time and today’s log has not been compiled since it last changed, spawns compile.py as another detached background process
The end-of-day auto-compile uses a SHA-256 hash stored in scripts/state.json to detect whether the daily log has changed since the last compilation. If the hash matches, compilation is skipped. If it differs, a new compile runs automatically without any cron job or scheduler.

​
Frequently asked questions

Long-running sessions can trigger multiple context-window compactions before you close the session. When Claude Code compacts, it summarizes the conversation — which discards context permanently. The PreCompact hook fires before each compaction and captures the current context to a daily log entry. Without it, anything discussed before a mid-session compaction is lost to the SessionEnd hook, which only sees the post-compaction transcript.Both hooks use identical architecture: extract context locally (no API calls), write to a temp file, spawn flush.py as a background process. The 60-second deduplication window in flush.py prevents duplicate entries when both hooks fire in quick succession at the end of a session.
flush.py sends the conversation context to Claude with a structured prompt that asks for:
  • Context: One line about what you were working on
  • Key Exchanges: Important Q&A or discussions
  • Decisions Made: Any decisions with their rationale
  • Lessons Learned: Gotchas, patterns, or insights discovered
  • Action Items: Follow-ups or TODOs mentioned
Claude is instructed to skip routine tool calls, trivial back-and-forth, and obvious content. If nothing in the session is worth saving, Claude responds with exactly FLUSH_OK and only a placeholder entry is written to the daily log. A typical flush costs $0.02–0.05.
Auto-compilation triggers at the end of the first flush that occurs after 6 PM local time, if today’s daily log has changed since it was last compiled. The threshold hour is set by COMPILE_AFTER_HOUR = 18 in flush.py.The check compares the SHA-256 hash of the current daily log against the hash stored in scripts/state.json from the last compile run. If the hashes differ, compile.py is spawned as a detached background process. If they match — meaning no new flushes have been appended since the last compile — the trigger is skipped.You can also run compile.py manually at any time:
uv run python scripts/compile.py              # compile new/changed logs only
uv run python scripts/compile.py --all        # force recompile everything
uv run python scripts/compile.py --dry-run    # preview without writing

Build docs developers (and LLMs) love

Get started for freeTalk to us