hippocampus-layer 1.0.0

Persistent memory + enforcement for agent-driven git repos — vendors the Hippocampus core (hooks, secret gates, CI floor) into any repo.

Hippocampus

Persistent memory + enforcement for agent-driven git repos. Vendors a config-driven core into any repo, so coding agents (Claude Code today) get three things that usually evaporate between sessions:

• Durable, git-tracked memory — decisions and project state that auto-load every session.
• Session handoff — each session ends by rewriting a baton the next one resumes from, enforced by a Stop-hook gate.
• Secret/PII enforcement — a push gate backed by a non-bypassable CI floor, plus scaffolding for your own gates and nudges.

Design principle: hooks are the fast layer, CI is the guarantee — every hard claim is backed by a CI job that runs for everyone, installed or not.

Early but installable, MIT-licensed. The packaged CLI is built and self-verified but not yet on PyPI.

Requirements

git · bash · python3 ≥ 3.11 (stock macOS python3 is 3.9 — install a newer one) · Claude Code for the interactive layer (without it you still get the CI floor and readable memory/handoff docs). Windows: WSL or Git-Bash.

Install

Two ways to vendor the core into your repo (a git repo, run at its root). Both are idempotent and merge-aware — an existing settings.json / CLAUDE.md / .gitignore is merged, never clobbered; re-run any time to pull engine updates.

CLI (once on PyPI — distribution hippocampus-layer, command hippocampus):

pip install hippocampus-layer
hippocampus init   /path/to/your/repo   # vendor the core
hippocampus doctor /path/to/your/repo   # 6-assertion smoke check

Until it's published: git clone …/hippocampus && uv build && pip install dist/*.whl.

install.sh (from a checkout — keep the checkout around; --check and updates run from it):

git clone https://gitlab.com/ianthill601/hippocampus.git
./hippocampus/install.sh /path/to/your/repo          # vendor
./hippocampus/install.sh --check /path/to/your/repo  # verify

Install writes the hooks, scanners, skills, scaffolds (.memory/, .workstate/, CLAUDE.md, hippocampus.toml, THREAT_MODEL.md) and a host-aware, floor-only CI pipeline (secret scan + config-drift check — no test job, since it never vendors your tests). Then commit the result and fill in CLAUDE.md / hippocampus.toml as you like.

Your own hooks go outside .claude/hooks/. Sync treats every hook under .claude/hooks/ as engine-owned and unwires anything there not registered via [[gates.custom]]. Put custom hooks under .claude/adopter-hooks/ and register them (see below); the installer warns if it finds unregistered ones.

What you get

• .memory/ — git-tracked memory the agent auto-loads; MEMORY.md routes one line per page. Plain markdown; review it in PRs.
• .workstate/ — the session baton (HANDOFF.md: what I did / next / repo state, HEAD-stamped) + open-work.md. A SessionStart hook injects it so each session resumes where the last landed.
• Landing gate — a Stop hook blocks ending a session that committed without updating the baton; the landing-the-plane skill satisfies it.
• Secret gate + CI floor + sweep — the push hook scans the outgoing commit range; the CI floor re-runs the scan for everyone (the guarantee, un-bypassable); a scheduled TruffleHog sweep catches history. On by default.
• /consolidate — periodic memory GC; the sole writer of CLAUDE.md, enforcing its line cap so it can't rot.
• CLAUDE.md laws — your standing rules, each badged 🔴 gated / 🟡 nudged / ⚪ advisory, honest about what's actually enforced.
• Config-activated (opt in via hippocampus.toml): declarative nudges, custom hard gates, a CI-static push gate (your lint/type commands), and a semantic auditor (ships off until you write THREAT_MODEL.md).

Without Claude Code, the CI floor and sweep still run at full strength and the memory/handoff/laws stay readable; the hooks and skills are Claude-Code-specific.

Configure — hippocampus.toml

The only file you edit. scripts/hippocampus_config.py is the sole reader and rejects unknown keys. Everything is optional; with no file, safe defaults apply (the landing + secret gates and CI floor are always on, not configured here). After editing, run python3 scripts/hippocampus_sync.py sync to regenerate the wiring.

[gates.ci_static]
commands = "just lint && just types"          # fast checks before a push (a single shell string)

[[gates.custom]]                              # register your own hook script (repeatable)
path = ".claude/adopter-hooks/require_lint.sh"   # repo-relative, tracked + executable
event = "PreToolUse"
matcher = "Bash"                              # optional tool matcher

[[nudges]]                                    # once-per-session reminder (repeatable)
match = "terraform apply"                     # regex tested against the command
message = "plan-diff reviewed? state backup taken?"
source = "docs/decisions.md#infra"            # optional provenance

[scan]
extra_pattern_file = "hippocampus-patterns.toml"   # your own [[pattern]] regex/label pairs
fixture_allowlist = ["tests/fake_creds.py"]   # secret-shaped-by-design files; paths only, max 10

[memory]
claude_md_cap = 100                           # /consolidate-enforced line cap on CLAUDE.md

[auditor]
threat_model = "THREAT_MODEL.md"

[paths]
decision_log = "docs/decisions.md"
onboarding_doc = "docs/onboarding.md"

Any path referenced above must exist and be git-tracked before you sync.

Seed it from your repo's history

Don't hand-write the config — have Claude Code mine an established repo for what it already enforces ad hoc and keeps re-learning, and draft the hippocampus.toml for you:

Read this repo's git history, CI config, test suite, and any docs/ADRs, then draft a
hippocampus.toml for it (schema: the config reference in the Hippocampus README — use only
those keys, no invented ones). Specifically:
- Mine `git log` for recurring fix/revert commits, post-incident changes, and repeated review
  comments — anything the team keeps re-learning — and propose a [[nudges]] entry (command
  regex → once-per-session reminder) for each pattern.
- Find the fast checks already run (lint/type/test in CI, Makefile, or package scripts) and set
  [gates.ci_static].commands to them.
- Identify hard rules the codebase treats as "never do this" and propose [[gates.custom]] gate
  scripts for them.
- Note any domain-specific secret/PII shapes the repo has leaked or already checks for and
  propose [scan].extra_pattern_file entries.
After each proposed entry, cite the commits or files that justify it. Propose nothing the repo
shows no evidence for.

Review the draft, drop what you don't want, commit it, and run hippocampus sync.

Known limitation

A first push from a branch with no upstream makes the secret gate scan all history (fail-closed) and disable the fixture allowlist — so it can false-positive on your own reviewed fixtures. Workaround: git push -u origin <branch> so it scans only the outgoing range. Deliberate, pending a narrower fallback.

License

MIT — © 2026 Ian Hill. Provided as-is, without warranty. Use it, fork it, vendor it into your repos.