Hippocampus MOS

Persistent memory for AI coding agents. Remembers every bug, decision, and pattern across sessions. Error Prevention Rate: 100%.

The Problem

Your AI coding agent fixes a nil pointer panic on Monday. On Wednesday, it introduces the exact same bug. Every session starts from zero — no memory of past errors, architectural decisions, or hard-won context.

Hippocampus fixes this. It runs as a local MCP server that gives your agent persistent memory across sessions.

Benchmark Results (52 test scenarios)

Quick Start

Option A: Docker (recommended — one command)

git clone https://github.com/samj6178/hippocampus.git
cd hippocampus
docker compose up -d

This starts Ollama (auto-pulls embedding model) + Hippocampus (SQLite, MCP + REST). Done.

Option B: Standalone binary (zero dependencies)

git clone https://github.com/samj6178/hippocampus.git
cd hippocampus
go build -o bin/hippocampus ./cmd/hippocampus/
./bin/hippocampus -config config.json

Works immediately in BM25 mode (keyword search). For semantic search, start Ollama separately:

ollama serve && ollama pull nomic-embed-text

Connect to Claude Code

Add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "hippocampus": {
      "command": "/path/to/hippocampus/bin/hippocampus",
      "args": ["-config", "/path/to/hippocampus/config.json"]
    }
  }
}

Connect to Cursor

Add to .cursor/mcp.json (same format as above).

How It Works

1. Error Prevention Pipeline

error occurs → mos_learn_error → structured pattern stored
                                        │
                                        ▼
                              consolidation clusters similar errors
                                        │
                                        ▼
                              prevention rule generated (WHEN/WATCH/DO)
                                        │
                                        ▼
                              next session: WARNING before touching that code
                                        │
                                        ▼
                              session end: git diff verifies the warning worked

Example: Agent creates &http.Client{} without Timeout. Hippocampus:

• Stores the error with root cause and fix
• Generates rule: "WHEN creating http.Client, WATCH for missing Timeout, DO set 30s timeout"
• Next session: agent sees the warning before writing HTTP code
• Session end: verifies the anti-pattern is absent from the diff

2. Four-Tier Memory (inspired by neuroscience)

3. Temporal Knowledge Graph

Track facts that change over time:

mos_kg_add("auth_service", "uses", "jwt")
# ... months later, after migration:
mos_kg_invalidate("auth_service", "uses", "jwt")
mos_kg_add("auth_service", "uses", "session_tokens")

# Query state at any point in time:
mos_kg_query("auth_service", as_of="2026-03-15")  → uses jwt
mos_kg_query("auth_service")                       → uses session_tokens
mos_kg_timeline("auth_service")                    → full history

4. Session Continuity

Session 1:
  mos_session_end(summary="Fixed recall bug", next_steps="Add room filter tests")

Session 2:
  mos_init → auto_context includes:
    ## Next Steps (from previous session)
    - Add room filter tests
    ## Known Pitfalls (DO NOT REPEAT)
    - ERROR: filterWeakCandidates nil pointer when embedding is nil
    ## Recent Sessions
    - [2h ago] Fixed recall bug...

5. Hybrid Retrieval

Recall uses Reciprocal Rank Fusion combining:

• Vector search (cosine similarity via Ollama embeddings)
• BM25 full-text search (SQLite FTS5)
• Keyword overlap scoring
• Recency decay (recent memories weighted higher)
• Importance scoring (errors and decisions weighted higher)

Cross-language: Russian queries find English memories (and vice versa) via embedding similarity.

Full Automation (recommended)

Add to ~/.claude/settings.json — Hippocampus runs fully automatically:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"additionalContext\":\"Call mos_init with the current workspace path NOW.\"}}'",
        "statusMessage": "Hippocampus: loading memory"
      }]
    }],
    "PostToolUseFailure": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"additionalContext\":\"A tool failed. Call mos_learn_error with the error, root cause, and fix.\"}}'",
        "statusMessage": "Hippocampus: capturing error"
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "echo '{\"hookSpecificOutput\":{\"additionalContext\":\"Session ending. Call mos_session_end with summary and next_steps.\"}}'",
        "statusMessage": "Hippocampus: saving session"
      }]
    }]
  }
}

Architecture

Single binary, clean architecture. Dependencies flow inward: adapter -> app -> domain.

cmd/hippocampus/          entry point, DI container
internal/
  domain/                 entities, interfaces (zero deps)
  app/                    services (encode, recall, consolidate, KG, mining...)
  adapter/
    mcp/                  MCP stdio server (35 tools)
    rest/                 REST API + embedded web dashboard
    llm/                  switchable LLM provider
  embedding/              Ollama/OpenAI-compatible embeddings
  repo/
    sqlite/               SQLite + FTS5 (default, zero-dep)
    (postgres)            PostgreSQL/pgvector (optional)
  memory/                 in-process working memory
  pkg/                    contenthash, roomclass, vecutil

Storage: SQLite by default (zero external dependencies). PostgreSQL/pgvector supported via config switch.

Embeddings: Ollama nomic-embed-text (768d, local, free). Any OpenAI-compatible API works (Jina, Voyage, OpenAI).

LLM: Agent-delegated by default — your Claude/GPT handles rule generation via two-phase delegation. No local model required.

35 MCP Tools

Session Lifecycle

Core Memory

Knowledge Graph

Learning

Analysis

Research

Projects

A/B Test: Warning Prevention

mos_ab_test runs 12 coding scenarios with known anti-patterns:

Treatment (warnings ON):   0 bugs, 12 clean    → 100% prevention
Control   (warnings OFF):  12 bugs, 0 clean    → 0% prevention
Lift: +100%

Categories: architecture, concurrency, error handling, injection, protocol, resource leaks.

Configuration

{
  "database": {
    "driver": "sqlite",
    "sqlite_path": "hippocampus.db"
  },
  "openai": {
    "mode": "cloud",
    "base_url": "http://localhost:11434/v1",
    "model": "nomic-embed-text",
    "dimensions": 768
  },
  "memory": {
    "gate_threshold": 0.3,
    "recall": {
      "absolute_floor": 0.30,
      "entropy_best": 0.45,
      "kw_check_threshold": 0.60
    }
  },
  "llm": {
    "provider": "none"
  }
}

Observability

• Health: GET /api/v1/health/ready
• Metrics: GET /metrics (Prometheus) — recall hit rate, prevention stats, embedding latency
• Dashboard: http://localhost:8080 — memory browser, project switcher, recall search
• Audit log: audit.jsonl — JSONL of all write operations

Development

go build ./...           # build
go test ./... -count=1   # unit tests (10 packages)
go vet ./...             # static analysis

License

MIT