hipocampus

The Problem

AI agents lose context between sessions and cannot surface relevant prior discussion unless the user explicitly asks for it. Existing solutions (RAG, huge context windows, plain BM25/Vector search) only work when the query hints at the missing knowledge. Hipocampus attempts to give agents a proactive “memory” that surfaces implicit context without a user query.

What This Does

Hipocampus provides a three‑tier memory stack (compaction tree + BM25 + vector) stored as plain files. The CLI (npx hipocampus …) builds the index, compacts history, and writes the artifacts under the repository root. Platform‑specific adapters live in platforms/, e.g. platforms/opencode/plugin/hipocampus.js for OpenCode and the .claude-plugin/ folder for Claude Code. The skills/ directory contains markdown specifications for the high‑level operations (compaction, flush, recall, search) that the CLI invokes.

How It Is Wired

Entry point – npx hipocampus init runs the hipocampus binary defined in package.json. The binary points to cli/init.mjs.

cli/init.mjs (732 lines) – parses CLI flags, decides which sub‑commands to run (compact, uninstall, etc.), and writes configuration files (templates/*.md). It is the sole orchestrator; no other module imports it.

cli/compact.mjs – reads the raw session logs, builds the compaction tree, and optionally generates BM25/vector indexes. The file contains an eval over a runtime‑constructed string (security risk).

cli/uninstall.mjs – removes generated indexes and template files; its logic mirrors compact.mjs with a similarly dense branch structure.

platforms/opencode/plugin/hipocampus.js – exports a plugin object that the OpenCode platform consumes; it calls the CLI scripts indirectly via child_process.exec to keep the memory up‑to‑date.

hooks/session-start.sh – a shell helper invoked by the platform when a new session begins; it contains duplicated 6‑line blocks also present in the CLI scripts.

Import graph – 5 internal modules, 0 import edges, 0 circular dependencies. Each CLI file is self‑contained, so a change in one script can affect the whole command flow (high blast radius).

Responsibility map

No hub or cycle appears; the cost is the lack of shared libraries, forcing duplicated code and large monolithic files.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/hipocampus
cd hipocampus

# 2. Install Node dependencies (no lockfile currently)
npm install

# 3. Initialise the memory stack (default builds all three tiers)
npx hipocampus init

# Optional flags (from README)
npx hipocampus init --no-vector      # BM25 only
npx hipocampus init --no-search      # Compaction tree only
npx hipocampus init --platform claude-code

No environment variables or external services are required; all data lives in the repository’s templates/ and generated index files. For Claude Code or OpenCode, install the plugin via the platform’s marketplace as described in the README, then the platform will call the same CLI under the hood.

Real‑World Use

A developer integrates the plugin into Claude Code:

// .claude-plugin/plugin.json
{
  "name": "hipocampus",
  "entry": "npx hipocampus init"
}

When a new chat session starts, the platform runs hooks/session-start.sh, which triggers cli/compact.mjs to update the compaction tree. Subsequent agent responses can query the tree via the skills/recall spec, allowing the agent to surface a rate‑limiting decision made weeks earlier without any explicit user prompt.

Code Health & Issues

• High – Missing lockfile – package.json present, no package-lock.json or pnpm-lock.yaml. Fix: run the package manager once and commit the generated lockfile.
• High – Unsafe eval – cli/compact.mjs executes eval() on a computed string. Fix: replace with safe parsing (e.g., JSON.parse).
• Medium – Dependabot not configured – No .github/dependabot.yml. Fix: add a Dependabot config covering npm.
• Medium – Duplicated code blocks – Same 6‑line snippet appears in cli/compact.mjs, cli/compact.test.mjs, cli/init.mjs, hooks/session-start.sh. Fix: extract to a shared helper module.
• Medium – Oversized file – cli/init.mjs is 732 lines, making reasoning and testing difficult. Fix: split by logical responsibilities (arg parsing, file generation, cleanup).
• Medium – High branching density – cli/compact.mjs and cli/uninstall.mjs each contain >100 branch points over ~300 lines. Fix: refactor into strategy tables or separate functions.

No CI pipeline, Dockerfile, or committed secrets were detected.

The Bottom Line

Hipocampus delivers a lightweight, file‑based proactive memory layer that demonstrably improves implicit‑context recall for AI agents. The implementation is functional but suffers from monolithic CLI scripts, duplicated logic, and security‑related eval usage. It is suitable for teams comfortable with Node.js who need a quick, no‑infrastructure memory add‑on, but they should address the highlighted health issues before production deployment.