hippocampus.md

Decay-based memory scoring and context lifecycle management. Part of the Agent Brain Architecture.

Protocol spec: https://hippocampus.md/whitepaper

Quick Install

npx hippocampus-md init

This auto-detects your platform (Pi/OpenClaw/Clawdbot) and installs the extension.

Entry Types & Decay Rates

Retention Formula

retention = max(floor, importance × e^(-λ × age))

Score Memory Files

# Score a specific file
npx hippocampus-md score memory/2026-02-03.md

# Output: memory/2026-02-03.scores.json

Check Status

npx hippocampus-md status

Manual Tagging

Tag entries in your daily notes for explicit scoring:

<!-- hippocampus: type=decision score=0.85 -->
Decided to use Railway for deployment.

<!-- hippocampus: type=user_intent score=0.72 -->
User wants the landing page done by Friday.

Configuration

Create hippocampus.config.json in workspace root:

{
  "enabled": true,
  "debug": false,
  "decay": {
    "decision": 0.03,
    "user_intent": 0.05,
    "context": 0.12,
    "tool_result": 0.20,
    "ephemeral": 0.35
  },
  "retention": {
    "sparse": 0.25,
    "compress": 0.65
  }
}

Defrag Integration

Scores integrate with defrag.md for nightly consolidation:

• •score < 0.25 → sparse index (pointers only)
• •0.25 ≤ score < 0.65 → compressed (summary)
• •score ≥ 0.65 → kept (full content)

Links

• •Docs: https://hippocampus.md
• •Whitepaper: https://hippocampus.md/whitepaper
• •GitHub: https://github.com/starvex/hippocampus-md

Part of the Agent Brain Architecture