hipocampo
🌐 Português · English
Persistent, git-versioned, human-gated memory for coding agents. Your agents
(Claude Code, Codex, Gemini) stop forgetting between sessions and stop letting
docs rot — in any project, any language.
Hipocampo (hippocampus) is the brain region that consolidates short-term
memory into long-term memory. The kit does the same: raw captures land in an
_inbox/, and a write-gated pipeline turns them into a curated, auditable
knowledge/ base that lives in your repo and compounds over time.
Status: v0.10.0 — usable. 182 tests, CI green, validated end-to-end including a
production project as first consumer, plus an opt-in semantic tier verified with
the deps installed and the kit dogfooding its own memory (details).
Quickstart (2 minutes)
/plugin marketplace add Ferraz2000/hipocampo-memory # Claude Code (skills + hooks)
/plugin install hipocampo@hipocampo
# or cross-agent (Claude Code / Codex / Gemini) — skills install natively:
npx skills add Ferraz2000/hipocampo-memory
On Codex and Gemini the skills are read natively (no wrapper); brain-scripts-init
also wires the session hooks for them. See Cross-agent support.
Then say /brain-init in your project. The agent does the setup — it asks
you three questions (language, where the vault lives, initial areas), generates
the config, and scaffolds the vault. From there, day-to-day is just talking:
/capture <something> # "remember this decision" → becomes a reviewable note
/search <terms> # "what do we know about X?"
That's all you need to start. Everything else is optional and the agent runs it
for you — see the full toolbox.
What it looks like (before / after)
Before — the agent changes a sensitive area; the doc silently rots:
$ git commit -m "feat: change persistence model"
[main abc1234] feat: change persistence model # doc drift starts here
After — the doc-sync gate (pre-commit → pre-push → CI, same rule) blocks it:
$ git commit -m "feat: change persistence model"
feature-doc-sync validation FAILED
Sensitive area changed without its doc update: persistence
Update one of: docs/architecture/persistence.md
$ git add docs/architecture/persistence.md && git commit ... # passes
And memory becomes a reviewable diff, not a black box:
+ docs/brain/knowledge/architecture/error-style.md # /capture wrote this
+ docs/brain/knowledge/index.md # +1 index line
Agent proposes → you approve → it lands in git. Validators keep it honest;
python -m hipocampo.canary proves the gates bite against your setup.
How it works
One principle: the human curates by talking; the agent does the bookkeeping.
| Layer | Where | Truth? |
|---|
| Rules (how to work here) | AGENTS.md / .claude/rules/ | yes |
| Working memory (in flight) | git-derived session briefing | no (cockpit) |
| Durable knowledge | knowledge/ + official docs | yes |
| Proposals ("should we?") | insights/ (scored) | not yet |
| Provenance | raw/sources/ (immutable) | anchor |
Reads are index-first: the agent reads a cheap knowledge/index.md and
loads only the relevant pages — never the whole vault (context-rot defense).
Writes go through a human write-gate (/capture): the agent proposes, you
approve, the agent files and reports.
What lands in your repo
/brain-init + /brain-scripts-init add, and the agent maintains:
brain.config.toml # all project-specific settings (generated, not hand-written)
docs/brain/ # the vault: knowledge/, insights/, raw/sources/, templates
hipocampo/ # vendored zero-dependency scripts (search, gates, hooks)
.githooks/ # pre-commit doc-sync gate + pre-push preflight
.github/workflows/ # optional: same gates in CI
Plain markdown + stdlib Python. No daemon, no database, no pip installs —
delete the folders and it's gone.
The full toolbox
21 skills, grouped — you don't memorize these; the agent picks them from what
you say. Adopt incrementally:
- Setup (once):
brain-init, brain-router-init, brain-scripts-init, brain-update.
- Daily:
capture, search, recall (agent pulls memory mid-task), low-token (lean mode).
- Thinking:
challenge (confront a decision with past reversals), discovery, spec, discover-standards.
- Insight lifecycle:
from-roadmap → promote → implement / execute-insight → weekly / postmortem / audit.
- Maintenance:
garden, archive-closed (+ the normalize fixer and the canary self-test).
Plus two session hooks (a session-start git briefing; a session-end capture-sweep
with secret redaction) — wired per agent — and six config-driven validators run
by preflight.
Cross-agent support
