From hipocampus
Implements 3-tier agent memory system with 5-level compaction tree for Claude Code. Manages session start protocols, compaction triggers, checkpoints, and memory files.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hipocampus:coreThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
Layer 1 (System Prompt — auto-loaded via @import):
SCRATCHPAD.md ~150 lines active working state
WORKING.md ~100 lines current tasks
TASK-QUEUE.md ~50 lines task backlog
memory/ROOT.md ~100 lines topic index of all memory (~3K tokens)
Long-term memory and user profile are managed by Claude Code's platform auto memory.
Layer 2 (On-Demand — read when needed):
memory/YYYY-MM-DD.md raw daily logs (permanent, never deleted)
knowledge/*.md detailed knowledge (searchable via qmd)
plans/*.md task plans
Layer 3 (Search — via qmd + compaction tree):
memory/daily/YYYY-MM-DD.md daily compaction nodes
memory/weekly/YYYY-WNN.md weekly compaction nodes
memory/monthly/YYYY-MM.md monthly compaction nodes
Tree traversal: ROOT → monthly → weekly → daily → raw
FIRST RESPONSE RULE: On the very first user message of every session, before doing ANYTHING else: Run the Session Start protocol below FIRST. This takes priority over ANY user request — even if the user asks you to do something specific. Complete the step below, ONLY THEN respond to the user.
SCRATCHPAD.md, WORKING.md, TASK-QUEUE.md, memory/ROOT.md are auto-loaded via @import in CLAUDE.md. No manual read needed.
This procedure must be completed before responding to the user NO MATTER WHAT
DO NOT SKIP DO NOT COMPROMISE Compaction maintenance (cooldown-gated):
Read memory/.compaction-state.json and hipocampus.config.json (compaction.cooldownHours, default 3).
Compaction triggers (any ONE is sufficient):
cooldownHours since lastCompactionRunrawLinesSinceLastCompaction > 300checkpointsSinceLastCompaction > 5cooldownHours is 0If no trigger is met: skip compaction subagent.
If any trigger is met: write memory/.compaction-state.json with { "lastCompactionRun": "<current ISO timestamp>", "rawLinesSinceLastCompaction": 0, "checkpointsSinceLastCompaction": 0 }, then dispatch compaction subagent.
State file is written immediately on dispatch (fire-and-forget), not after subagent completion. The cooldown tracks "a compaction was initiated," not "a compaction succeeded."
This step is MANDATORY every session. You MUST read the state file and make the judgment. The only thing that may be skipped is the subagent dispatch when no trigger is met. This procedure must be completed before responding to the user NO MATTER WHAT
When the user's question may relate to past memory, use the hipocampus-recall skill for structured retrieval. See hipocampus/skills/recall/SKILL.md.
After completing any task, dispatch a subagent to append a structured log to memory/YYYY-MM-DD.md.
Compose the subagent task:
Append the following to memory/YYYY-MM-DD.md:
[Topic Name] [type]
- request: [what the user asked]
- analysis: [what you researched/analyzed]
- decisions: [choices made with rationale]
- outcome: [what was done, files changed]
- references: [knowledge/ files, external sources]
Where
typeis: project | feedback | user | referenceFor feedback entries, use:
[Feedback Topic] [feedback]
- rule: [the behavioral rule]
- why: [reason given]
- how-to-apply: [when/where this applies]
The subagent only needs to do one thing: append to the daily log. This is the source of truth — everything else (SCRATCHPAD, WORKING, TASK-QUEUE) is updated lazily at next session start or by the agent naturally during work.
After appending to the daily log, the subagent should also increment the checkpoint counter in memory/.compaction-state.json: read the file, increment checkpointsSinceLastCompaction by 1, write back. If the file or field is missing, start from 0.
The subagent needs the task summary you provide — it doesn't have access to the conversation.
Priority if timeout imminent (no time for subagent — write directly to memory/YYYY-MM-DD.md)
Do not wait for task completion to write to the daily log. Proactively dispatch a subagent to append to memory/YYYY-MM-DD.md when:
Compose the subagent task with a summary of what to dump, same as the checkpoint format. The subagent writes the file; the main session stays clean.
This protects against context compression — if the platform compresses your conversation history, undumped details are lost forever. Write early, write often. The daily log is append-only, so multiple dumps in the same session are fine.
When composing checkpoint content for the subagent, exclude:
[REDACTED].| File | Target | When Exceeded |
|---|---|---|
| ROOT.md | ~100 lines (~3K tokens) | Automatic recursive self-compression |
| SCRATCHPAD | ~150 lines | Remove completed items |
| WORKING | ~100 lines | Remove completed tasks |
| TASK-QUEUE | ~50 lines | Archive completed items |
memory/YYYY-MM-DD.md): permanent. Never delete or edit after session.npx claudepluginhub kevin-hs-sohn/hipocampus --plugin hipocampusManually dumps current session context to daily raw log via subagent. Invoke with /hipocampus:flush to persist sessions without waiting for checkpoints. Follow with hipocampus:compaction for full processing.
3-tier markdown memory protocol (shared/agent/conversation) for cross-session knowledge accumulation. Automatically injects relevant memory into agent context at task start.
Manually saves important session context (decisions, facts, tasks) to a daily memory log without triggering native context compaction. Useful for explicit checkpoints on CLI or messaging channels.