hippocampus-mcp

Working memory for Claude Code. Preserves task context across /compact so Claude never loses track of what it was doing.

Claude Code's /compact summarizes the conversation to free up context — but it often loses the details that matter:

• What you were working on right now
• What was already decided and done
• What the next step was supposed to be

After compaction, Claude drifts, re-asks settled questions, or forgets progress entirely.

hippocampus works like the brain structure it's named after — it manages a memory lifecycle:

• Recent memories stay detailed
• Older memories auto-compress to summaries
• Trivial memories eventually disappear

Claude records milestones as it works. hippocampus handles the rest — compression, cleanup, and restoration — without any AI involvement.

claude mcp add hippocampus -- npx -y @julskim/hippocampus-mcp

That's it. No hooks, no config files, no CLAUDE.md edits. hippocampus injects its own instructions into Claude's system prompt via the MCP protocol. Claude automatically knows when to save and restore.

Every milestone has both a detail (full context) and summary (one-liner), written by Claude at save time. hippocampus mechanically transitions between them based on age:

DETAIL ──age──→ SUMMARY ──age──→ DELETED (minor only)
                   │
                major stays here
               (deleted only on capacity overflow)

Time is measured in chat cycles (question-answer pairs), not wall-clock time. A week of inactivity doesn't age memories — only actual interactions do.

major = feature implementation, architecture decision, bug fix, multi-file refactor minor = config change, formatting, single-file tweak, docs

Call after completing a meaningful milestone, or before /compact.

session_id     — Claude Code session ID
project_dir    — current working directory
current_task   — what you're doing now (one sentence)
next_step      — what to do next (one sentence)
event?         — milestone to record
  importance   — "major" or "minor"
  detail       — full context (what, where, how)
  summary      — one-line compressed version

Call after /compact or context summary to restore working context.

session_id     — Claude Code session ID
→ Returns: MemoryView (current_task + next_step + age-compressed journey)

List all sessions or inspect a specific one.

Remove a specific entry or an entire session.

All settings are optional. Defaults work well for most use cases.

Pass via MCP server config:

{
  "mcpServers": {
    "hippocampus": {
      "command": "npx",
      "args": ["-y", "@julskim/hippocampus-mcp"],
      "env": {
        "HIPPOCAMPUS_MAX_ENTRIES": "50"
      }
    }
  }
}

The MCP instructions handle everything automatically. But if you want to guarantee saves before every compact:

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Context is about to be compacted. Use hippocampus save_memory to preserve your current working state.",
            "timeout": 30
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Context was compacted. Use hippocampus load_memory to restore your working state.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

This MCP server handles working memory — what Claude is doing, where, and how. That makes security non-negotiable.

This project is maintained by a single developer. Every line of code is reviewed and shipped by one person. External pull requests are NOT accepted — not because contributions aren't valued, but because a single chain of trust is the strongest defense against supply chain attacks.

You're free to fork, modify, and build your own version under the MIT license. But the official @julskim/hippocampus-mcp package on npm will always trace back to one verified author.

Bug reports and feature requests are welcome. Open a GitHub Issue — every report is reviewed and addressed promptly. No PR needed; just describe the problem or idea, and it will be handled.

Running a solo-maintained security-conscious project takes time. If hippocampus saved your context (and your sanity), consider supporting its development:

• Crypto: 0xe5C8742E13F1c007978eb08C848e39CE16CCE4E2 (ETH / Polygon / Base)

MIT