hipocampus plugin
hipocampus gives an agent file-based memory: a 3,000-token topic index loads each session and shows what came up before
- 211 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Writes memory files into the project and edits agent settings during init
- Session log contents go to the model for compaction and search, and may hold secrets and project decisions
- qmd-based search downloads models and takes about 2 GB
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/hipocampusDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Writes memory files into the project and edits agent settings during init
- Session log contents go to the model for compaction and search, and may hold secrets and project decisions
- qmd-based search downloads models and takes about 2 GB
This is third-party code. Review the repository files before installing.
What it does
hipocampus is a plugin and memory skill set for Claude Code, OpenCode, Codex and OpenClaw. All memory lives in plain files inside the project and no infrastructure is required. Setup is one command, and `npx hipocampus init` configures the platform and search. Memory has three layers. The hot layer loads into every session: a `memory/ROOT.md` topic index of about three thousand tokens, plus `SCRATCHPAD.md`, `WORKING.md` and `TASK-QUEUE.md`. Each topic carries a type (project, feedback, user, reference) and an age, so the agent sees what it knows and how fresh it is. The warm layer is read on demand: daily logs, `knowledge/` and `plans/`. The cold layer is searched through a BM25 plus vector hybrid on qmd or through a compaction tree from daily to weekly, monthly and root nodes. Entries compact by thresholds: short ones are copied verbatim, long ones are summarized by the model. User corrections and user facts are kept verbatim forever, and reference entries get a marker after 30 days without verification. When a question comes up the agent follows three steps: the topic index, file selection by headings, and keyword search.
Who it is for. People who run long projects with Claude Code or OpenCode and are tired of reminding the agent of decisions from three weeks ago.
Good fit when
- The agent refactors a payment flow while the rate-limit decision was made in another session
- A project runs for months and session logs grow faster than anyone rereads them
- You want style and approach corrections to persist and not be compacted until revoked
- Memory should live as plain files in the repository that you can see and edit by hand
- You want one memory setup for Claude Code, OpenCode, Codex and OpenClaw
Not a fit when
- You need shared cloud memory for a team: data lives as files inside one project
- Disk is tight: vector search needs about 2 GB, although `--no-vector` skips it
- The project is short and a `CLAUDE.md` rules file is enough
- You use an agent outside the platform list: automatic platform detection does not know it
Example request
Before editing the payments module, open ROOT.md and tell me which rate-limit and retry decisions we made earlierLimitations
- Claude Code, OpenCode and OpenClaw are supported, and Codex has a separate skill. The platform can be set with the `--platform` flag.
- Vector search needs about 2 GB of disk, `--no-vector` keeps BM25 only, and `--no-search` turns search off and keeps the compaction tree.
- Long entries are summarized by a model, so compaction spends tokens.
- The MemAware results belong to the author: on the hard tier the method scores 8.0 percent, which the author ties to the answering model rather than the index size.
How to disable. Remove the plugin through the Claude Code plugin manager. Memory is stored as files in the project (`memory/`, `knowledge/`, `plans/`), so delete those folders by hand if unwanted. Remove by hand the lines in agent settings that `npx hipocampus init` added.
FAQ
How do I install hipocampus in Claude Code?
Run `/plugin marketplace add kevin-hs-sohn/hipocampus` and `/plugin install hipocampus@kevin-hs-sohn/hipocampus`, then run `npx hipocampus init` to set up memory in the project.
How does hipocampus differ from ordinary RAG?
RAG answers a query, whereas here a topic index already sits in context and hints at connections nobody asked about. Search remains for exact details.
What is ROOT.md?
A compressed index of the whole history: active context for the week, recent patterns, a monthly summary and a list of topics with type and age. It takes about three thousand tokens and loads automatically.
Can I skip vector search?
Yes. The `--no-vector` flag keeps BM25 only and saves about 2 GB, and `--no-search` keeps only the compaction tree with no search.
Which platforms are supported?
Claude Code, OpenCode and OpenClaw with auto-detection, and a separate skill for Codex in the platforms folder. The `--platform` flag forces a choice.
Discussion
No questions or reviews yet.
Related
PluginsShared memory for Claude Code, Codex and Cursor: a decision made in one session is recalled in another tool or on another machine.
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
The Supermemory plugin for Claude Code: persistent memory across sessions with automatic prompt recall, conversation capture and a codebase index
A long-term memory plugin that keeps decisions, preferences and task state across sessions and injects only what a query needs
A local workbench for Claude Code, Codex, Pi and OpenCode: memory changes wait for your review, then an audit follows each turn
Persistent memory for coding agents: insights are stored as markdown cards and recalled at the start of the next session.
README in short
The README opens with MemAware benchmark results on 900 questions and a comparison with BM25 and vector search. It then argues that you cannot search for what you do not know you know. Sections describe the three memory layers, smart compaction, entry types and the recall order.