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 a pure Python project managed by uv. Installation takes under two minutes: clone the repo, run one command, and the toolchain is ready. All three dependencies are pinned in pyproject.toml and installed into an isolated virtual environment automatically.

​
Prerequisites

Before you begin, make sure the following are available on your machine:
  • Python 3.12 or later — required by pyproject.toml’s requires-python = ">=3.12"
  • uv — the package manager used to install and run everything (installation guide)
  • Claude Code with a Claude Max, Team, or Enterprise subscription — the hooks rely on Claude Code’s built-in credentials and the Claude Agent SDK

​
Installation steps

1

Clone the repository

Clone the project into your local machine:
git clone https://github.com/coleam00/claude-memory-compiler
cd claude-memory-compiler
2

Install dependencies with uv

Run uv sync from the project root. This creates a virtual environment and installs all three dependencies:
uv sync
The dependencies declared in pyproject.toml are:
[project]
name = "llm-personal-kb"
version = "0.1.0"
description = "Personal knowledge base compiled from AI conversations - inspired by Karpathy's LLM KB architecture"
requires-python = ">=3.12"
dependencies = [
    "claude-agent-sdk>=0.1.29",
    "python-dotenv>=1.0.0",
    "tzdata>=2024.1",
]
  • claude-agent-sdk — makes LLM calls with tool use for compilation, querying, and linting
  • python-dotenv — loads environment variables from .env if present
  • tzdata — timezone data for end-of-day auto-compilation logic
3

Verify the installation

Confirm the scripts are importable and the CLI flags work:
uv run python scripts/compile.py --dry-run
uv run python scripts/query.py --help
uv run python scripts/lint.py --structural-only
A successful dry-run prints Nothing to compile - all daily logs are up to date. on a fresh clone (no daily logs exist yet). That output confirms the environment is working.
No API key is needed. The Claude Agent SDK authenticates using Claude Code’s built-in credentials stored at ~/.claude/.credentials.json. As long as you have an active Claude Max, Team, or Enterprise subscription and have signed in to Claude Code at least once, the SDK will authenticate automatically.

​
Project structure

After cloning, the repository has the following layout (from AGENTS.md): 
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)
The daily/ and knowledge/ directories are created automatically the first time the hooks run. The scripts/state.json and scripts/last-flush.json state files are also generated automatically and are gitignored. The next step is configuring the Claude Code hooks so your conversations start being captured automatically — see Set up Claude Code hooks.

Build docs developers (and LLMs) love

Get started for freeTalk to us