Beginners

What is this tool?

claude-memories is a CLI that optimizes how Claude Code loads your memory files. Claude Code stores context in a MEMORY.md file that grows over time. Every session loads the entire file, which can consume 40K+ tokens of your context window — most of it irrelevant to the current task.

claude-memories parses your MEMORY.md, extracts topic references, and generates a dispatch table (index.json). With this table, an agent can load only the memory topics that match the current task instead of everything at once.

The tool is local-only (no network calls, no telemetry), read-mostly (it never modifies your MEMORY.md), and deterministic (same inputs always produce the same outputs).

Who is this for?

• Claude Code users whose MEMORY.md has grown beyond a few thousand tokens and want to reclaim context window budget
• Agent developers building on the Knowledge OS stack who need machine-readable dispatch tables for memory routing
• Teams managing shared memory files across multiple Claude Code projects

You do not need this tool if your MEMORY.md is small (under 2K tokens) or if you only have a handful of memory topics.

Prerequisites

• Node.js 20 or later — check with node --version
• A MEMORY.md file — this is the file Claude Code creates automatically at ~/.claude/projects/<project>/memory/MEMORY.md
• Topic files — the individual .md files that MEMORY.md references with arrow syntax (e.g., Topic Name → \memory/topic.md“)

No API keys, accounts, or network access required.

Your First 5 Minutes

Step 1: Install

npm install -g @mcptoolshop/claude-memories

Step 2: Find your MEMORY.md

If you are not sure where it lives, run the health check:

claude-memories health

This scans common locations and tells you what it finds.

Step 3: Analyze

claude-memories analyze MEMORY.md

This shows you sections, references, missing files, orphan files, and token costs. Review the output to understand your memory structure.

Step 4: Generate a dispatch table

claude-memories index MEMORY.md --lazy

This writes memory/index.json next to your MEMORY.md. The --lazy flag marks all entries as on-demand, meaning they load only when an agent task matches their keywords.

Step 5: Validate

claude-memories validate MEMORY.md

Fix any errors (missing files, broken references) before relying on the index.

Common Mistakes

Using the wrong path. claude-memories needs the path to your MEMORY.md file, not a directory. If you get a FILE_NOT_FOUND error, double-check the path.

Expecting MEMORY.md edits. claude-memories never modifies your MEMORY.md or topic files. It only reads them and writes index.json. If you want to reorganize your memory, edit MEMORY.md by hand.

Forgetting the arrow format. The parser expects topic references in this format:

Topic Name — description → `memory/topic-file.md`

Lines that do not match this pattern (or the backtick-path variant) are skipped. Plain prose paragraphs are ignored.

Ignoring validate warnings. Orphan files (topic files not referenced in MEMORY.md) waste disk space and cause confusion. Duplicate references inflate your token budget estimates. Run validate after any structural changes.

Mixing up frontmatter id with filename. When no frontmatter is present, the entry id is derived from the topic name in MEMORY.md (converted to kebab-case), not from the filename. For example, AI Loadout becomes ai-loadout regardless of what the file is called.

Next Steps

• Read the Usage guide for the full command reference including all flags and options
• Read the Architecture page to understand how claude-memories fits into the Knowledge OS stack alongside ai-loadout and claude-rules
• Add optional frontmatter to your topic files for fine-grained control over keywords, priority, and trigger conditions
• Run claude-memories stats MEMORY.md to see a detailed token budget dashboard with your top entries by cost

Glossary

Term	Definition
MEMORY.md	The markdown file where Claude Code stores auto-generated memories about your project. Grows over time as you work.
Topic file	An individual .md file referenced from MEMORY.md that contains detailed notes about a specific subject (e.g., memory/ai-loadout.md).
Dispatch table	The index.json file generated by claude-memories index. Maps keywords to topic files so an agent can load only what it needs.
Arrow format	The reference syntax used in MEMORY.md: Name — description → \path“. The parser uses this to discover topic files.
Frontmatter	Optional YAML metadata at the top of a topic file (between --- fences) that overrides auto-extracted keywords, priority, and triggers.
Token budget	The estimated context window cost of your memory files. “Always loaded” is the cost of MEMORY.md itself; “on-demand” is the cost of topic files loaded only when matched.
Lazy loading	When enabled (--lazy flag), all entries are marked as on-demand. The agent loads topic files only when their keywords match the current task.
Priority	How urgently a topic should be loaded. core = always loaded, domain = loaded when keywords match, manual = loaded only by explicit request.
Orphan file	A .md file in the memory directory that is not referenced by any entry in MEMORY.md. Found by validate.
Knowledge OS	The broader stack that claude-memories belongs to. The kernel is ai-loadout; adapters like claude-memories and claude-rules convert different document types into compatible dispatch tables.