tinchak0207/Hippocampus

Hippocampus: Let the agent learn from mistakes

Write lessons learned into notes/, compile them into an index with mem build, and before starting a similar task, look up how you failed before. The CLI is called mem.

The memory root directory is $MEM_HOME (default ~/.claude/memory). Everything is plain text; mem build generates the other three tiers from notes/.

When to use

• Before starting a non-trivial task: check if this task was done before, whether there are any decisions or pitfalls.
• When the user mentions "last time", "as previously said", or "per the usual rules".
• Before dispatching a subagent: include relevant memory in the spec.
• After completing a reusable result, solving a recurring issue, or being corrected by the user: write a note.

Four-tier model

Tier	File	Content	Who writes
Tier-0	MEMORY.md	Routing table: read/write protocol, pack list, last 12 notes; has a byte budget (default 12000)	mem build
Tier-1	packs/<id>.md	One page per domain, each note gets one line with description + path	mem build
Tier-2	catalog.tsv	One line per note: pack date type name title bytes gist	mem build
Tier-3	notes/*.md	Original text with YAML front-matter	mem add creates the file, you fill in the content

Classification rules are in $MEM_HOME/.memorypack/packs.json: if the front-matter metadata.pack contains a valid ID, it uses that; otherwise, it scores by keywords (strong +3, keywords +1); zero score goes to misc.

Read path (follow in order, stop when enough is found)

1. Read the entire MEMORY.md (it is small and designed to be read in full).
2. Find the domain by "when to read" → mem pack <id> to skim that domain.
3. To locate specific entries → mem find <keyword> [--pack <id>] [--limit N], returns only catalog lines.
4. For only the 1-3 matched entries → mem show <name> to read the full note.

When memory conflicts with live evidence (code, logs, command output), defer to live evidence and inform the user which memory is outdated.

Write path (only this one)

mem add <slug> --type project|feedback|reference [--pack <id>] [--title "title"]
# Open the printed path, fill in one line of description + FACT / decision / pitfall / related
mem build

• description is the only content that appears in the upper three tiers; write it as "what this is + when to use it" in one sentence.
• To edit an existing note: directly edit the file in notes/, then mem build.
• After writing, run mem doctor to check budget, broken links, and missing descriptions.

Prohibitions

• Do not manually edit MEMORY.md, packs/*, or catalog.tsv: they are generated artifacts and will be overwritten on the next build.
• Do not batch-read notes/ (cat notes/*, ls then read each file, grep the entire directory for raw text): use mem find.
• Do not delete notes unless explicitly asked by the user; for outdated notes, mark them in the original text and update the description.
• Do not write secrets, tokens, passwords, private keys, or personally identifiable information into notes.
• Do not create a second memory store; symlink old paths from other tools to $MEM_HOME.

Reference

• Daily maintenance: prompts/maintain.md
• End-of-session review and proactive building: prompts/proactive-build.md
• Rules snippet ready to paste into AGENTS.md / CLAUDE.md: prompts/agents-snippet.md
• Hooks examples: prompts/hooks/