Metadata-Version: 2.4
Name: hippocampus-layer
Version: 1.0.0
Summary: Persistent memory + enforcement for agent-driven git repos — vendors the Hippocampus core (hooks, secret gates, CI floor) into any repo.
Project-URL: Homepage, https://gitlab.com/ianthill601/hippocampus
Project-URL: Repository, https://gitlab.com/ianthill601/hippocampus
Author: Ian Hill
License: MIT
License-File: LICENSE
Keywords: agent-memory,claude-code,coding-agents,developer-tools,git-hooks,secret-scanning,session-handoff
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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`):
```sh
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):
```sh
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.

```toml
[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:

```text
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](LICENSE) — © 2026 Ian Hill. Provided as-is, without warranty. Use it, fork it, vendor it into your repos.
