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.

The Claude Memory Compiler organises files into four top-level directories. daily/ holds immutable conversation logs. knowledge/ holds the compiled output the LLM writes and maintains. scripts/ holds the CLI tools. hooks/ holds the Claude Code automation layer. Understanding which layer owns which files — and how they reference each other — is the key to navigating and extending the system.

​
Full project tree

llm-personal-kb/
|-- .claude/
|   |-- settings.json                # Hook configuration (auto-activates in Claude Code)
|-- .gitignore                       # Excludes runtime state, temp files, caches
|-- AGENTS.md                        # Schema + full technical reference
|-- README.md                        # Concise overview + quick start
|-- pyproject.toml                   # Dependencies (at root so hooks can find it)
|-- daily/                           # "Source code" - conversation logs (immutable)
|-- knowledge/                       # "Executable" - compiled knowledge (LLM-owned)
|   |-- index.md                     #   Master catalog - THE retrieval mechanism
|   |-- log.md                       #   Append-only build log
|   |-- concepts/                    #   Atomic knowledge articles
|   |-- connections/                 #   Cross-cutting insights linking 2+ concepts
|   |-- qa/                          #   Filed query answers (compounding knowledge)
|-- scripts/                         # CLI tools
|   |-- compile.py                   #   Compile daily logs -> knowledge articles
|   |-- query.py                     #   Ask questions (index-guided, no RAG)
|   |-- lint.py                      #   7 health checks
|   |-- flush.py                     #   Extract memories from conversations (background)
|   |-- config.py                    #   Path constants
|   |-- utils.py                     #   Shared helpers
|-- hooks/                           # Claude Code hooks
|   |-- session-start.py             #   Injects knowledge into every session
|   |-- session-end.py               #   Extracts conversation -> daily log
|   |-- pre-compact.py               #   Safety net: captures context before compaction
|-- reports/                         # Lint reports (gitignored)

​
Directory roles

​
daily/ — immutable source

Daily logs are the raw material of the system. They are append-only: flush.py adds entries to them, but nothing ever edits or deletes them after the fact. Think of them as version-controlled source files — the compiler reads them but never modifies them. Each file is named YYYY-MM-DD.md and contains structured session entries written by flush.py.
Do not edit daily log files manually. If a log is changed after compilation, the SHA-256 hash stored in scripts/state.json will no longer match, and lint will flag the article as stale. Run compile.py --file to recompile after any intentional edit.

​
knowledge/ — LLM-owned compiled output

The knowledge/ directory is fully owned and maintained by the LLM. Humans read it but should rarely edit it directly. The three subdirectories map to the three article types:
DirectoryArticle typeCreated by
knowledge/concepts/Concept articlescompile.py
knowledge/connections/Connection articlescompile.py
knowledge/qa/Q&A articlesquery.py --file-back
Two structural files sit at the knowledge/ root: knowledge/index.md is the master catalog and the primary retrieval mechanism. Every article has a row in this table. When query.py answers a question, it reads index.md first to select which full articles to fetch — no vector search needed. knowledge/log.md is an append-only chronological record of every compile, query, and lint operation. It is never overwritten, only appended to.

​
scripts/ — CLI tools

Contains the four user-facing scripts (compile.py, query.py, lint.py, flush.py) plus shared infrastructure (config.py for path constants, utils.py for helpers). State files (state.json, last-flush.json) are also stored here at runtime but are gitignored.

​
hooks/ — Claude Code automation

Contains the three hook scripts that fire automatically when Claude Code sessions start, end, or trigger auto-compaction. These are the entry points that make the system fully automatic.

​
reports/ — lint output (gitignored)

lint.py writes its markdown reports here as lint-YYYY-MM-DD.md. The directory is gitignored so reports don’t accumulate in version control. They are regenerated on the next lint run.

​
Structural files

​
knowledge/index.md — master catalog

The index is a markdown table. Every article appears as one row, giving the LLM a structured overview of the entire knowledge base before it reads any article in full. 
# Knowledge Base Index

| Article | Summary | Compiled From | Updated |
|---------|---------|---------------|---------|
| [[concepts/supabase-auth]] | Row-level security patterns and JWT gotchas | daily/2026-04-02.md | 2026-04-02 |
| [[connections/auth-and-webhooks]] | Token verification patterns shared across Supabase auth and Stripe webhooks | daily/2026-04-02.md, daily/2026-04-04.md | 2026-04-04 |
compile.py adds rows when it creates new articles and updates the Updated column when it modifies existing ones. query.py --file-back adds rows for filed Q&A articles.

​
knowledge/log.md — build log

An append-only chronological record. Every major operation appends a timestamped entry: 
# Build Log

## [2026-04-01T14:30:00] compile | Daily Log 2026-04-01
- Source: daily/2026-04-01.md
- Articles created: [[concepts/nextjs-project-structure]], [[concepts/tailwind-setup]]
- Articles updated: (none)

## [2026-04-02T09:00:00] query | "How do I handle auth redirects?"
- Consulted: [[concepts/supabase-auth]], [[concepts/nextjs-middleware]]
- Filed to: [[qa/auth-redirect-handling]]

​
State tracking

Two JSON files in scripts/ track runtime state. Both are gitignored and regenerated automatically.

​
scripts/state.json

Tracks compilation history and cumulative costs. 
{
  "ingested": {
    "2026-04-01.md": {
      "hash": "a1b2c3d4e5f6g7h8",
      "compiled_at": "2026-04-01T14:30:00+00:00",
      "cost_usd": 0.52
    }
  },
  "query_count": 14,
  "last_lint": "2026-04-05T10:00:00+00:00",
  "total_cost": 8.37
}
KeyDescription
ingestedMap of daily log filenames to their last-seen SHA-256 hash (first 16 hex chars), compilation timestamp, and cost
query_countTotal number of queries run with query.py
last_lintISO 8601 timestamp of the most recent lint.py run
total_costCumulative API cost across all operations in USD

​
scripts/last-flush.json

Tracks deduplication for the background flush process. 
{
  "session_id": "abc123",
  "timestamp": 1743897600.0
}
If flush.py is called twice for the same session_id within 60 seconds (which can happen when both pre-compact.py and session-end.py fire in quick succession), the second call reads this file and exits without running the LLM.

Build docs developers (and LLMs) love

Get started for freeTalk to us