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.

query.py lets you ask natural language questions against your compiled knowledge base. Instead of a vector database or embeddings, it uses index-guided retrieval: the LLM reads knowledge/index.md first to understand what articles exist, selects the 3–10 most relevant ones, reads them in full, and synthesizes a cited answer. This approach outperforms cosine similarity at personal knowledge base scale and requires no infrastructure beyond what is already installed.

​
CLI commands

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

# Ask a question and file the answer back into the knowledge base
uv run python scripts/query.py "What's my error handling strategy?" --file-back

​
The --file-back flag

Without --file-back, the answer is printed to stdout and discarded. With --file-back, the query engine does three additional things after synthesizing the answer:
  1. Creates a Q&A article in knowledge/qa/ with a slugified filename (e.g., knowledge/qa/whats-my-error-handling-strategy.md) using the full Q&A article format from AGENTS.md
  2. Adds a new row to knowledge/index.md for the filed Q&A article
  3. Appends a timestamped entry to knowledge/log.md recording the question, which articles were consulted, and where the answer was filed
This is the compounding loop: every question you file back makes the knowledge base smarter. Future queries and sessions will have access to the synthesized answer, not just the raw concept articles it was derived from.

​
How index-guided retrieval works

The retrieval flow mirrors the instructions in query.py’s prompt: 
prompt = f"""You are a knowledge base query engine. Answer the user's question by
consulting the knowledge base below.

## How to Answer

1. Read the INDEX section first - it lists every article with a one-line summary
2. Identify 3-10 articles that are relevant to the question
3. Read those articles carefully (they're included below)
4. Synthesize a clear, thorough answer
5. Cite your sources using [[wikilinks]] (e.g., [[concepts/supabase-auth]])
6. If the knowledge base doesn't contain relevant information, say so honestly
...
"""
The entire knowledge base — index plus all articles — is loaded into the context window as a single structured string. The LLM reads the index table first, reasons about which articles are relevant to the question being asked, then reads those articles in full before synthesizing a response with [[wikilink]] citations back to the source articles.
Why no RAG? At personal knowledge base scale (50–500 articles), the LLM reading a structured index.md outperforms vector similarity. Embeddings find similar words; the LLM finds relevant concepts. Cosine similarity cannot understand that a question about “auth redirects” is answered by an article titled “Next.js middleware patterns” — but the LLM can. RAG becomes necessary only when the knowledge base grows to roughly 2,000+ articles and the index itself exceeds the context window. See Using your knowledge base in Obsidian for notes on scaling.

​
Knowledge base health checks

lint.py runs seven checks against your knowledge base to catch problems before they accumulate. Run it periodically, especially after several compilations. 
# Run all 7 checks (6 structural + 1 LLM contradiction check)
uv run python scripts/lint.py

# Run only the 6 structural checks — no API calls, no cost
uv run python scripts/lint.py --structural-only
Reports are saved to reports/lint-YYYY-MM-DD.md.

​
The 7 checks

CheckTypeSeverityWhat it catches
Broken linksStructuralError[[wikilinks]] pointing to articles that do not exist on disk
Orphan pagesStructuralWarningArticles with zero inbound links from any other article
Orphan sourcesStructuralWarningDaily logs in daily/ that have not been compiled yet
Stale articlesStructuralWarningDaily logs that changed on disk since their last compilation
Missing backlinksStructuralSuggestionArticle A links to article B, but B does not link back to A
Sparse articlesStructuralSuggestionArticles under 200 words, likely incomplete
ContradictionsLLMWarningConflicting or inconsistent claims across different articles
The contradiction check is the only one that calls the Claude Agent SDK. Use --structural-only to run the other six checks for free at any time.

Build docs developers (and LLMs) love

Get started for freeTalk to us