Script reference — compile, query, lint, flush

The Claude Memory Compiler ships four CLI scripts that cover every operation in the knowledge-base lifecycle: compiling daily logs into articles, querying the knowledge base, linting for health issues, and flushing conversation context in the background. All scripts are run with uv run python scripts/<script>.py from the project root.

compile.py

Reads daily conversation logs from daily/ and uses the Claude Agent SDK to extract concepts, decisions, and lessons into structured wiki articles under knowledge/. This is the core “LLM compiler” step — it turns raw source logs into the queryable knowledge base. Compilation is incremental by default: the script tracks SHA-256 hashes of each daily log in scripts/state.json and skips files that haven’t changed since the last run.

Flags

--all

flag

default:"false"

Force recompile all daily logs, even those whose hashes haven’t changed since the last compilation. Use this after editing AGENTS.md or when you want fresh extraction passes over existing logs.

--file

string

Compile a single daily log file instead of scanning all of daily/. Accepts a path relative to the project root or relative to daily/ (e.g. daily/2026-04-01.md or 2026-04-01.md).

--dry-run

flag

default:"false"

Print the list of files that would be compiled without actually running any LLM calls. Useful for verifying which logs are stale before committing to API costs.

Invocations

# Compile only new or changed daily logs (default)
uv run python scripts/compile.py

# Force recompile every log regardless of hash
uv run python scripts/compile.py --all

# Compile a specific log
uv run python scripts/compile.py --file daily/2026-04-01.md

# Preview what would be compiled without running the LLM
uv run python scripts/compile.py --dry-run

Outputs

Output	Description
`knowledge/concepts/*.md`	New or updated concept articles extracted from the log
`knowledge/connections/*.md`	New connection articles when cross-concept relationships are found
`knowledge/index.md`	Master catalog updated with new and modified article entries
`knowledge/log.md`	Timestamped compile entry appended with articles created and updated
`scripts/state.json`	`ingested` map updated with SHA-256 hash, compile timestamp, and cost for each compiled log

Compile cost scales with the size of the knowledge base. As knowledge/index.md and the existing articles grow, more tokens are sent to the LLM on each run. Expect

0.45–

0.65 per daily log early on, rising gradually as the KB grows.

query.py

Loads the entire knowledge base into context — the index plus all concept, connection, and Q&A articles — and asks the Claude Agent SDK to synthesize an answer to a free-form question. No vector database or embedding lookup is used; the LLM reasons directly over the structured index.md to select which articles are relevant.

Arguments

question

string

required

The question to ask the knowledge base. Pass it as a quoted positional argument. The LLM reads knowledge/index.md first, selects 3–10 relevant articles, then synthesizes an answer with wikilink citations.

--file-back

flag

default:"false"

After answering, create a permanent Q&A article in knowledge/qa/ and update knowledge/index.md and knowledge/log.md. This is the compounding loop: every filed answer makes future queries smarter.

Invocations

# Ask a question and print the answer to stdout
uv run python scripts/query.py "What auth patterns do I use?"

# Ask and permanently file the answer as a Q&A article
uv run python scripts/query.py "What's my error handling strategy?" --file-back

Outputs

Output	Description
stdout	Synthesized answer printed to the terminal with `[[wikilink]]` citations
`knowledge/qa/<slug>.md`	Q&A article created when `--file-back` is set
`knowledge/index.md`	New Q&A entry added when `--file-back` is set
`knowledge/log.md`	Query entry appended with consulted articles and filed location
`scripts/state.json`	`query_count` and `total_cost` incremented

lint.py

Runs up to seven health checks against the knowledge base and saves a markdown report to reports/lint-YYYY-MM-DD.md. Six checks are structural (free, instant, no API calls); the seventh uses the LLM to detect semantic contradictions.

Flags

--structural-only

flag

default:"false"

Skip the LLM contradiction check. Only the six structural checks run, making lint completely free and near-instant. Recommended for frequent automated runs; reserve full lint for periodic deep checks.

Invocations

# Run all 7 checks including LLM contradiction detection
uv run python scripts/lint.py

# Run only the 6 structural checks (free)
uv run python scripts/lint.py --structural-only

The seven checks

#	Check	Type	Severity	What it catches
1	Broken links	Structural	Error	`[[wikilinks]]` pointing to articles that do not exist on disk
2	Orphan pages	Structural	Warning	Articles with zero inbound links from other articles
3	Orphan sources	Structural	Warning	Daily logs in `daily/` that have never been compiled
4	Stale articles	Structural	Warning	Source daily logs that changed after their last compilation hash was recorded
5	Missing backlinks	Structural	Suggestion	A links to B but B does not link back to A (auto-fixable)
6	Sparse articles	Structural	Suggestion	Articles under 200 words, likely incomplete
7	Contradictions	LLM	Warning	Conflicting or inconsistent claims across articles

Outputs

Output	Description
`reports/lint-YYYY-MM-DD.md`	Markdown report with error, warning, and suggestion sections
`scripts/state.json`	`last_lint` timestamp updated

Run --structural-only as a free pre-commit check. Reserve full lint (with the LLM contradiction pass) for weekly or on-demand runs to keep costs low.

flush.py

A background worker that extracts memorable knowledge from a conversation transcript and appends it to today’s daily log. It is not meant to be invoked directly by users — both session-end.py and pre-compact.py spawn it as a detached background process after each session.

Arguments

context_file.md

string

required

Path to a temporary .md file containing the pre-extracted conversation context written by the hook. The file is deleted by flush.py after processing.

session_id

string

required

The Claude Code session identifier, passed through from the hook’s stdin payload. Used for deduplication: if the same session_id is flushed within 60 seconds, the second call is silently skipped.

Environment variables

CLAUDE_INVOKED_BY

string

Set automatically to memory_flush at the top of flush.py before any other imports. This prevents the Claude Agent SDK subprocess from triggering session-end.py or pre-compact.py again, breaking the recursion loop.

Invocations

# Spawned automatically by hooks — not normally called directly.
# Signature for reference:
uv run python scripts/flush.py <context_file.md> <session_id>

What flush.py does

Recursion guard

Sets CLAUDE_INVOKED_BY=memory_flush immediately on startup to prevent hooks from re-firing when the Agent SDK spawns its own Claude Code subprocess.

Deduplication check

Reads scripts/last-flush.json. If the same session_id was flushed within the last 60 seconds, exits silently and deletes the context file.

LLM extraction

Calls the Claude Agent SDK with allowed_tools=[] and max_turns=2. Claude reviews the conversation context and returns either structured bullet points (Context, Key Exchanges, Decisions Made, Lessons Learned, Action Items) or the literal string FLUSH_OK if nothing is worth saving.

Daily log append

Appends the structured entry to daily/YYYY-MM-DD.md, creating the file with a header if it does not exist yet.

End-of-day compilation

If the local time is past COMPILE_AFTER_HOUR (default 18, i.e. 6 PM) and today’s log hash differs from the last recorded hash in scripts/state.json, spawns compile.py as another detached background process.

Outputs

Output	Description
`daily/YYYY-MM-DD.md`	New session entry appended (or file created if first session of the day)
`scripts/last-flush.json`	Deduplication state updated with `session_id` and current timestamp
`scripts/flush.log`	Execution log (only observable channel since stdout is suppressed)
`compile.py` (subprocess)	Spawned after 6 PM if today’s log has new content since the last compile

Do not call flush.py manually while a Claude Code session is active. The recursion guard relies on CLAUDE_INVOKED_BY being absent in the hook’s environment; running flush directly from a terminal inside Claude Code will not cause harm but may produce unexpected log entries.

Get Started

Guides

Reference

Script reference — compile, query, lint, flush

compile.py

Flags

Invocations

Outputs

query.py

Arguments

Invocations

Outputs

lint.py

Flags

Invocations

The seven checks

Outputs

flush.py

Arguments

Environment variables

Invocations

What flush.py does

Outputs

Build docs developers (and LLMs) love

Get Started

Guides

Reference

Documentation Index

​compile.py

​Flags

​Invocations

​Outputs

​query.py

​Arguments

​Invocations

​Outputs

​lint.py

​Flags

​Invocations

​The seven checks

​Outputs

​flush.py

​Arguments

​Environment variables

​Invocations

​What flush.py does

​Outputs

Build docs developers (and LLMs) love

compile.py

Flags

Invocations

Outputs

query.py

Arguments

Invocations

Outputs

lint.py

Flags

Invocations

The seven checks

Outputs

flush.py

Arguments

Environment variables

Invocations

What flush.py does

Outputs