claude-memory-compiler

---
name: claude-memory-compiler
description: Give Claude Code an evolving memory that captures sessions, extracts decisions and lessons via the Claude Agent SDK, and compiles everything into structured cross-referenced knowledge articles.
triggers:
  - set up claude memory compiler
  - give claude code persistent memory
  - capture my coding sessions automatically
  - compile my claude conversations into a knowledge base
  - set up session hooks for claude code
  - install llm knowledge base for my project
  - make claude remember decisions across sessions
  - auto-capture claude code session transcripts
---

# Claude Memory Compiler

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Claude Memory Compiler gives Claude Code a persistent, evolving memory. Claude Code hooks automatically capture conversation transcripts at session end or pre-compaction. A background process using the Claude Agent SDK extracts decisions, lessons, and patterns, appending them to daily logs. A compiler then organizes those logs into structured, cross-referenced knowledge articles — no vector database or RAG required at personal scale.

Inspired by [Karpathy's LLM Knowledge Base](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) architecture.

---

## Installation

### Option 1 — Tell your AI agent

Clone https://github.com/coleam00/claude-memory-compiler into this project. Set up the Claude Code hooks so my conversations automatically get captured into daily logs, compiled into a knowledge base, and injected back into future sessions. Read the AGENTS.md for the full technical reference.

### Option 2 — Manual setup

```bash
# Clone into your project root
git clone https://github.com/coleam00/claude-memory-compiler .claude-memory

cd .claude-memory

# Install dependencies (requires uv)
uv sync

# Copy hooks config into your project's Claude settings
cp .claude/settings.json ../.claude/settings.json
# Or merge the hooks block into an existing .claude/settings.json

Dependency requirements

• Python 3.10+
• uv package manager
• Claude Code (with Max, Team, or Enterprise subscription — no separate API credits needed)

---

How It Works

Conversation
  -> SessionEnd / PreCompact hooks
  -> flush.py  (Claude Agent SDK extracts knowledge)
  -> daily/YYYY-MM-DD.md
  -> compile.py (after 6 PM or manually)
  -> knowledge/concepts/, connections/, qa/
  -> SessionStart hook injects index.md into next session
  -> cycle repeats

Hook events used

Hook	Purpose
SessionEnd	Primary capture — fires when a session closes
PreCompact	Safety net — fires before mid-session compaction
SessionStart	Injects the knowledge index into each new session

---

Key Commands

# Compile new daily logs into knowledge articles
uv run python scripts/compile.py

# Ask a question against the knowledge base
uv run python scripts/query.py "Why did we switch from SQLite to Postgres?"

# Ask + save the answer back into the knowledge base
uv run python scripts/query.py "What auth strategy are we using?" --file-back

# Run all 7 health checks (broken links, orphans, contradictions, staleness)
uv run python scripts/lint.py

# Run only free structural checks (no LLM calls)
uv run python scripts/lint.py --structural-only

---

Directory Structure

your-project/
├── .claude/
│   └── settings.json          # Hook configuration
├── daily/
│   └── YYYY-MM-DD.md          # Raw daily session logs
├── knowledge/
│   ├── index.md               # Master index (injected at session start)
│   ├── concepts/              # Structured concept articles
│   ├── connections/           # Cross-reference articles
│   └── qa/                    # Q&A articles saved with --file-back
└── scripts/
    ├── flush.py               # Session capture + extraction
    ├── compile.py             # Daily logs -> knowledge articles
    ├── query.py               # Index-guided retrieval
    └── lint.py                # Knowledge base health checks

---

Configuration — .claude/settings.json

{
  "hooks": {
    "SessionEnd": [
      {
        "command": "uv run python scripts/flush.py",
        "cwd": "${workspaceFolder}"
      }
    ],
    "PreCompact": [
      {
        "command": "uv run python scripts/flush.py --pre-compact",
        "cwd": "${workspaceFolder}"
      }
    ],
    "SessionStart": [
      {
        "command": "uv run python scripts/inject.py",
        "cwd": "${workspaceFolder}"
      }
    ]
  }
}

If you already have a .claude/settings.json, merge only the hooks block — don't overwrite existing settings.

---

Code Examples

Manually flush a transcript

# scripts/flush.py is called automatically by hooks, but you can invoke it directly
import subprocess

result = subprocess.run(
    ["uv", "run", "python", "scripts/flush.py"],
    capture_output=True,
    text=True
)
print(result.stdout)

Programmatic query

# Query the knowledge base from your own scripts
import subprocess
import sys

def query_knowledge_base(question: str, save_back: bool = False) -> str:
    cmd = ["uv", "run", "python", "scripts/query.py", question]
    if save_back:
        cmd.append("--file-back")
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.stdout

answer = query_knowledge_base("What database migration strategy are we using?")
print(answer)

Trigger compilation manually

import subprocess

def compile_knowledge():
    """Compile all unprocessed daily logs into knowledge articles."""
    result = subprocess.run(
        ["uv", "run", "python", "scripts/compile.py"],
        capture_output=True,
        text=True
    )
    if result.returncode != 0:
        print("Compile error:", result.stderr)
    else:
        print(result.stdout)

compile_knowledge()

Run lint checks programmatically

import subprocess

def lint_knowledge_base(structural_only: bool = False) -> dict:
    cmd = ["uv", "run", "python", "scripts/lint.py"]
    if structural_only:
        cmd.append("--structural-only")
    result = subprocess.run(cmd, capture_output=True, text=True)
    return {
        "passed": result.returncode == 0,
        "output": result.stdout,
        "errors": result.stderr
    }

report = lint_knowledge_base(structural_only=True)
print(report["output"])

---

Daily Log Format (daily/YYYY-MM-DD.md)

Each flush appends an entry like:

## Session — 2026-04-10 14:32

### Decisions
- Switched auth from JWT to session cookies to simplify SSR compatibility.

### Lessons Learned
- `prisma migrate dev` resets the shadow DB on every run — use `--skip-generate` in CI.

### Patterns Identified
- All new API routes follow the `app/api/[resource]/route.ts` convention.

### Gotchas
- The `useRouter` hook from `next/navigation` behaves differently in Server Components — always import from the correct package.

---

Knowledge Article Format (knowledge/concepts/)

Compiled articles use structured markdown:

# Authentication Strategy

**Last Updated:** 2026-04-10
**Related:** [[Session Management]], [[API Security]]

## Summary
We use session cookies (not JWTs) for authentication to simplify SSR compatibility with Next.js App Router.

## Key Decisions
- Chose session cookies over JWTs on 2026-04-08 after discovering JWT refresh complexity with RSC.

## Lessons
- Always import `useRouter` from `next/navigation` in client components, never from `next/router`.

## Open Questions
- Should we add refresh token rotation for long-lived sessions?

---

Automatic Compilation Trigger

flush.py checks local time after each session. If it is after 6 PM, it automatically triggers compile.py to process that day's logs. This means no manual scheduling is needed for end-of-day compilation.

To compile at any time:

uv run python scripts/compile.py

---

Why No RAG / Vector Database?

At personal scale (50–500 articles), the LLM reads knowledge/index.md directly and understands context better than cosine similarity over embeddings. RAG becomes necessary only at ~2,000+ articles when the index exceeds the context window.

The index file (knowledge/index.md) is a plain markdown table of contents injected at session start — giving Claude full awareness of what's been learned without any retrieval infrastructure.

---

Subscription & Cost Notes

• Runs on Claude Max, Team, or Enterprise subscriptions — no separate API billing required
• Anthropic has confirmed personal use of the Claude Agent SDK is covered under existing subscriptions
• lint.py --structural-only runs broken-link and orphan checks without any LLM calls (free)
• LLM-powered lint checks (contradiction detection, staleness) consume subscription usage

---

Common Patterns

Pattern: Bootstrap a new project

# 1. Clone the compiler into your project
git clone https://github.com/coleam00/claude-memory-compiler .

# 2. Install dependencies
uv sync

# 3. Merge hooks into .claude/settings.json (see Configuration section)

# 4. Open Claude Code — hooks activate automatically on next session

Pattern: Recover after a missed session

If hooks failed to fire, manually flush by running flush.py with the transcript path (check AGENTS.md for the exact CLI flags your version supports):

uv run python scripts/flush.py --transcript path/to/transcript.json

Pattern: Keep the knowledge base healthy

Run this weekly:

# Free structural check first
uv run python scripts/lint.py --structural-only

# Full check (uses LLM credits) when issues are suspected
uv run python scripts/lint.py

Pattern: Answer a question and persist it

uv run python scripts/query.py "What's our strategy for handling database migrations in CI?" --file-back
# Answer is printed AND saved to knowledge/qa/YYYY-MM-DD-slug.md

---

Troubleshooting

Problem	Solution
Hooks not firing	Confirm .claude/settings.json exists in your project root with the correct hooks block
uv not found	Install uv: curl -Lsf https://astral.sh/uv/install.sh | sh
uv sync fails	Ensure Python 3.10+ is active; run uv python install 3.12 if needed
Compilation produces empty articles	Check daily/ for logs; flush may not have run — open and close a Claude Code session
query.py returns vague answers	Run compile.py first to ensure daily logs are compiled into the index
Lint reports broken links	Article was renamed or deleted; update cross-references in the affected files
Session injection not working	Verify the SessionStart hook is present in settings and knowledge/index.md exists

---

Full Technical Reference

See AGENTS.md in the repository for:

• Complete article schema definitions
• Hook architecture internals
• Script CLI flags and extension points
• Cross-platform (Windows/macOS/Linux) hook path details
• Customization options for extraction prompts
• Cost breakdown per operation