githippo

[githippo, a hippocampus for your AI]

[CI] [MCP server] [MIT] [Node 20+] [Your own repo]

Claude forgets everything when the context compacts.
githippo doesn't.

[githippo surviving a context compaction in Claude Code]

Long-term memory for Claude and any MCP client, stored as plain Markdown in a git repo you own. Hybrid semantic search, a knowledge graph, auto-memory and compaction survival, at about 790 tokens of tool overhead per turn. Every memory is a git commit you can read, diff and revert.

curl -fsSL https://raw.githubusercontent.com/AnxovatomicaES/githippo/main/install.sh | sh

That's the whole install: no account, no token, no questions. It sets up a local memory vault, wires Claude Code (hooks, MCP, status line) and fetches semantic search in the background. Restart Claude Code and just talk; it remembers.

Want it backed up and synced across machines? githippo sync --github creates a private repo with your existing GitHub CLI login and pushes after every change. Just curious? npx -y github:AnxovatomicaES/githippo#v3.9.3 demo shows it working in 30 seconds without installing anything.

[Deploy to Render]
_{one click → use it from claude.ai and your phone}

Why another memory server?

Because each good idea out there lives in a different tool. githippo takes the best of each and fixes the part that hurts:

Version 3.1 adds the best idea from each of nine other memory tools, read in their source and credited in docs/prior-art.md: <private> tags, compaction steering and summary capture, session diffing, activity-aware decay, a code-aware tokenizer, errors in checkpoints, an honest status line, plugin packaging and alwaysLoad registration.

What else it does:

• Compliance guard. Blocks private keys (including PGP) and API tokens (Anthropic, OpenAI, GitHub, AWS, Slack, Stripe, Google, SendGrid, npm, Hugging Face, JWTs), password and secret assignments (password: …, DB_PASSWORD=…, AWS_SECRET_ACCESS_KEY=…), connection strings with embedded passwords, card security codes, IBANs (mod-97 checked, spaces or hyphens), card numbers (Luhn checked, even with other digits beside them), Spanish DNI/NIE, French NIR (checksums), UK National Insurance numbers (written in capitals) and US SSNs before they become permanent git history. It reads through lookalike letters, other scripts' digits and zero-width characters, and plain prose such as "password: required", "tokens: 128000" or a Spanish date like "12/10/26" is left alone. It also catches opaque Authorization: Bearer/Basic headers, GitLab, Google OAuth, Slack and Discord webhook and bot tokens, Telegram, Twilio, Mailgun, Azure, Shopify, PyPI and DigitalOcean tokens, STRIPE_KEY=-style environment lines, PINs, and the quoted-JSON, markdown-bold and "the password is …" forms of a password. A secret that is base64-encoded, split across words or URL-encoded still gets through: it is a backstop, not DLP.
• Compaction-proof by design, three ways (see below).
• Cross-lingual recall. The default multilingual embedder runs locally; ask in Spanish, find notes written in English.
• Updates are never mistaken for duplicates. "Launch is end of Q1" and "end of Q2" embed almost identically. githippo also compares numbers, dates and names, so the update is saved, the old line is flagged, and maintain reports possible contradictions. Measured in docs/calibration.md. When each fact has a content word the other lacks ("dark" / "light", "weekly" / "monthly", "read" / "write"), they are never called duplicates either, because neither keyword overlap nor embeddings can tell a synonym from an opposite: the new fact is saved and flagged as a possible update, and maintain lists the pair as a possible contradiction. (Before this rule, half of a set of twelve such pairs were silently dropped in keyword mode.)
• Optimistic concurrency. Two sessions editing the same memory can't clobber each other; the loser gets the current file back and merges.

Survives compaction, three layers deep

When Claude Code compacts a long session, the conversation gets summarised and details die. githippo makes sure what matters doesn't.

flowchart LR  A[Context fills up] --> B[PreCompact hook]  B -->|parse transcript, no LLM| C[checkpoint: goal, todos, files, where it stopped]  C --> D[(local ~/.githippo)]  C --> E[(repo sessions/)]  F[Compaction] --> G[SessionStart hook, source=compact]  D --> G  G -->|injects the state itself, not a reminder to read it| H[Claude continues exactly where it stopped]  I[MCP instructions + core memory] -.->|system prompt, never compacted| H

1. Core memory in the system prompt. MCP server instructions aren't part of the conversation, so compaction can't touch them. Your pinned facts are always there, in any MCP client.
2. Hook-driven checkpoint (Claude Code). A common complaint is that a post-compaction hook which only reminds Claude to re-read a state file is hit or miss. githippo injects the content directly. The checkpoint is capped at about 900 tokens; when a session is too big for that it drops the lowest-value detail first (the earlier summary, commands, older requests, finished tasks) and never the goal, the open tasks or where it stopped.
3. checkpoint tool (any client, including claude.ai). Claude saves task, state and next step at milestones. After context loss, checkpoint with no args restores it.

Bonus: a fresh session in the same project and branch within 24h gets a brief "last time you were…" note, including what changed in git since (commits, commits by others, branch switches, deleted files). The UserPromptSubmit hook proactively surfaces up to three relevant memories when the match is confident. It's capped at 300 tokens, skips trivial prompts and never repeats within a session. Words in your prompt that the vault has never seen count against a match, so an ordinary coding prompt that shares two generic words with a note ("refactor", "use") is not given memory: on 1,000 to 10,000 notes none of 20 unrelated coding prompts triggered an injection, while all 40 planted questions did, with the right note (test/report6-hook.test.js). Before compaction, githippo also tells the compactor what must survive, and after compaction it keeps the compactor's summary with the checkpoint.

How we know the hooks do what we say: the contracts were read from Claude Code's own code (2.1.258). PreCompact passes each successful hook's stdout to the compactor as custom instructions (Claude Code also shows that text in the transcript as "PreCompact … completed successfully"); PostCompact receives compact_summary; every hook receives session_id, transcript_path and cwd; SessionStart sources are startup, resume, clear, compact and fork.

Recall also learns what you actually use: memory that keeps being handed to Claude gets a small boost (at most +40% on its keyword score, +10% on its semantic score) that halves every 30 days without use. It is applied to those raw scores, so it only reorders results that were nearly tied: it can't push a clear match out of first place (an earlier version applied it after rank fusion and did, see test/report6-ranking.test.js). The counts stay on your machine, are kept per user, and with no usage data ranking is exactly the same as without it.

Wrap anything in <private>…</private> and it never reaches memory. An opening tag that is never closed makes everything after it private, and remember refuses the fact and tells you why, rather than silently keeping the part you meant to hide. Turn hooks off without editing files: GITHIPPO_HOOK_PROFILE=minimal or GITHIPPO_DISABLED_HOOKS=prompt,steer.

Quality, measured (and what isn't)

Retrieval, on a small labelled set (52 queries) and on LongMemEval-S (500 questions, retrieval only, no LLM):

Reproduce the first with githippo eval. Method, per-language breakdown, filing and duplicate accuracy, memory use and scale numbers are in docs/benchmarks.md. The set is small, hand-written by the author and in-domain: a regression guard and a rough guide, not a leaderboard.

Not measured yet, and it is the number that matters most: whether answers get better, or sessions cheaper, with githippo than without it. eval/qa.js and eval/behavior.js are built to measure exactly that and need an ANTHROPIC_API_KEY; they have not been run. Until they are, read "saves tokens" as: it adds a bounded cost to every turn (below) and pays that back only when a recalled fact replaces re-explaining or re-discovering something. If you run them, post the results in issue #3.

Should you use githippo?

• Claude's built-in memory is the zero-setup choice. Use githippo if you want the memory as files you can read, diff, edit in Obsidian and back up yourself, the same memory across Claude Code, Claude Desktop, claude.ai and other MCP clients, or memory that survives Claude Code's context compaction.
• basic-memory is the closest alternative: also Markdown and Obsidian-friendly, more mature, Python, AGPL. githippo differs in git history and time travel, the compaction hooks, OAuth team vaults with folder permissions, and a secrets guard.
• mem0 and other hosted services extract facts with an LLM and store them in their cloud, with nothing to run. githippo never calls an LLM to save a fact and keeps everything in a repo you own.
• It's new. githippo is a single-maintainer project (first commit October 2026) that strangers have not yet run at scale. The benchmark, 200+ tests, a seeded fuzzer that runs nightly, five rounds of audit findings (test/report*.test.js: each reproduced first, then fixed with a regression test) and the release notes are there so you can judge it, but expect rough edges.

Claude-native features (opt-in, measured)

The last three cost API credits per run, which is why they're opt-in and why their results aren't in this README yet.

Token budget (measured, githippo bench)

How: terse schemas, the redundant $schema URL stripped from tools/list, compact text responses instead of pretty JSON, wikilinks rendered as plain words, frontmatter stripped, 8-char version handles, History/index/sessions/core excluded from recall by default, and token budgets on every pack.

What that costs per turn, worst case: tool schemas ~790 + instructions ~200 + core memory up to 400 (CORE_BUDGET_TOKENS) is about 1,400 tokens, plus up to 300 on prompts where the per-prompt hook finds a confident match, plus whatever recall returns (about 47 for mode=brief, up to 1,000 for a pack by default). The schemas, instructions and core are a stable prefix, so a client that uses prompt caching pays less than the raw count. githippo does not save tokens by existing: it saves them when a recalled fact replaces re-explaining or re-discovering something.

And in time: the hooks run before every prompt and the status line runs constantly, so their start-up is kept minimal (they load none of the server code). On the development machine githippo bench reports about 57 ms for a hook and 60 ms for the status line, against 39 ms for node alone; it was 125 ms until the server's imports were made lazy. Run githippo bench to see your own.

Tools

Setup

Platforms: Linux and macOS are tested in CI on every change; Windows is not supported yet (what fails and why is in docs/platforms.md), and WSL should behave like Linux.

Claude Code (full experience: hooks + MCP)

curl -fsSL https://raw.githubusercontent.com/AnxovatomicaES/githippo/main/install.sh | sh

Prefer to see what runs? It's a short shell script: check Node 20+, npm i -g github:AnxovatomicaES/githippo#v3.9.3, then githippo setup. setup is idempotent, keeps any status line you already have, and backs up ~/.claude/settings.json before touching it. githippo doctor checks everything afterwards (and exits non-zero if a check fails). githippo uninstall removes the hooks, status line and MCP entry again and leaves your memory alone; githippo <command> --help explains any command, and a mistyped option stops with a suggestion instead of running.

Coming from the official reference memory server? githippo import ~/path/to/memory.jsonl turns its entities, observations and relations into notes and typed links (secrets guard and dedupe apply, so re-running is safe).

Plugin route: run the install above (for the githippo command), then /plugin marketplace add AnxovatomicaES/githippo and /plugin install githippo. The plugin supplies the hooks and the MCP server, and githippo setup / githippo install notice it and don't add a second copy (that used to run every hook twice). If you already have both, run githippo uninstall and keep the plugin. Or hand your agent INSTALL_FOR_AGENTS.md.

githippo sync --github            # creates a private repo "githippo-memory" with your gh login

githippo users add john --acl "shared/:write,people/:read"   # prints his password oncegithippo users list

Memory format

Plain Markdown, Obsidian-compatible. Open the repo as a vault and you get the graph view for free.

---name: billing-v2title: Billing v2type: projectdescription: Billing rewritealiases: [billing rewrite]---
## Decisions- Use idempotency keys on every write endpoint- owner:: [[sam-okafor]]- Launch target is end of Q1
## History- ~~Launch target is end of Q4~~ (until 2026-09-30)

Layout: core.md (pinned), index.md (table of contents), inbox.md (unrouted facts), people/, projects/, topics/, decisions/, sessions/ (checkpoints). See examples/memory.

Note names can contain spaces, accents and any script (my notes.md, café.md, 笔记.md), so a vault synced from Obsidian works as it is. Only names that are unsafe everywhere are refused (control characters, \ < > : " | ? *, hidden names). Frontmatter is treated as untrusted: odd values (title: [], huge fields, __proto__) can't break search, and a single unreadable note is skipped with a warning instead of taking memory down. Notes containing unresolved git conflict markers are never indexed or written to, and githippo refuses to write while a merge or rebase is unfinished.

Configuration

One rule everywhere: environment variable, then ~/.githippo/config.json, then the default. The ones most people touch: VAULT_DIR (default ~/.githippo/vault), EMBEDDINGS (local, static, voyage or none), GITHIPPO_CONFIRM (auto, strict or off) and PROMPT_RECALL=0 (turn off the per-prompt hook). Everything else, including the remote-server and team-vault variables, is in docs/configuration.md.

Security model, honestly

• Your files, your data. githippo has no backend. Memory lives in a folder on your machine; backup goes to a private repo you own. githippo asks GitHub anonymously whether the backup remote is publicly readable: githippo doctor fails if it is, githippo sync won't push to it and the background push refuses (override on purpose with GITHIPPO_ALLOW_PUBLIC_BACKUP=1). It can only check GitHub remotes; on another host, check the repository's visibility yourself.
• No stored token for local use. Sync uses git's existing login (GitHub CLI, SSH or keychain). Only the remote server needs a token: make it fine-grained, one repo, Contents read/write only.
• Remote auth is OAuth 2.1 (PKCE S256 only, dynamic client registration, single-use codes, tokens bound to the /mcp resource and to the user's current password and ACL). Refresh tokens rotate: each works once, and presenting a spent one (a sign it was copied) revokes everything from that sign-in, access tokens included; reusing an authorization code does the same. Signing is stateless (HMAC), so restarts don't log anyone out. The old secret-in-URL (/mcp/<secret>) is off unless LEGACY_SECRET_URL=1, because URLs end up in proxy logs. The server answers malformed requests with 400 instead of dying, validates every body, throttles repeated failed logins, caps and counts JSON-RPC batches per call, and rate-limits by socket address.
• The guard is a backstop, not DLP. It catches common secret and ID formats. forget removes a line from the current file, but git history keeps it; purging needs a history rewrite.
• Folder permissions hold up to tricks. Team-vault paths are normalised once and the permission check and the store use that same path, so whitespace, invisible characters, .. and (on case-insensitive disks) case changes, including the way macOS and Windows fold ſ, ß and fi, can't slip past a rule. index.md shows each reader only the notes they can read, and a name that two readable notes claim sends the fact to your inbox instead of guessing. Another user's users/<id>/ folder stays closed to catch-all rules.
• Core memory is the most trusted text, so it has one door. Through the tools it is written only by pin (confirmed with you where your client supports it, and refused for facts from outside sources), never by remember about:"core" or the files tool; lines that came from outside sources never load into it, and its token budget is a hard cap on what loads.
• Remote sessions can't be asked. Confirmation uses MCP elicitation, and a stateless HTTP request has no channel for it, so on the remote server GITHIPPO_CONFIRM=auto never asks. Set GITHIPPO_CONFIRM=strict there if you want facts from outside sources, pins to core memory and removals refused instead of allowed unconfirmed.
• Anyone can register an OAuth app under any name. Dynamic client registration is open (that is how claude.ai connects), so the sign-in page shows where your browser will be sent next and says to continue only for a connection you started.
• Outside text stays data. Facts from web pages, files or tool output are marked [external] and keep that mark through moves, rewrites and consolidation. Text that reads like instructions aimed at an AI is refused (on every write route: remember, the files tool, the memory tool and LLM rewrites; checked as written and as recall will show it, so a comment, a link alias or an invisible character doesn't hide it). That screen is a heuristic for the common phrasings, not a guarantee: a paraphrase gets through, which is why core memory has its own door and facts from outside are marked. Checkpoints neutralise such text and can't be made to forge sections.
• Git state is respected. githippo won't touch a merge or rebase you started, never commits conflict markers, and treats bisect, a detached HEAD or a linked worktree as "busy" and says so.
• Hooks never break your session, and don't need githippo on the PATH. Every failure path exits 0 with a short timeout. On macOS and Linux setup writes the absolute paths of node and githippo into the hooks, the status line and the MCP entry, so they work when Claude Desktop or an IDE starts Claude Code with a shorter PATH than your shell; if that node moved they try node, then githippo, from the PATH, and when none runs (githippo was uninstalled) they do nothing. Re-running githippo setup after moving or reinstalling brings an earlier entry up to date, and githippo doctor says if the pinned path is gone. (The Claude Code plugin's hooks still look githippo up on the PATH.)
• Known limits. The .mcpb bundle is not code-signed yet, a deleted fact lives on in git history until you rewrite it, and the benefit to answer quality is not yet measured (see above).

Develop

npm ci && npm test      # 200+ tests: unit, hooks, adopted features, bug regressions, local vault, setup, end-to-end over Streamable HTTP with the official MCP clientnpm run fuzz            # seeded fuzzing of every entry point (FUZZ_SEED=<n> FUZZ_ITERATIONS=<k> to reproduce or go deeper); runs nightly in CI with a fresh seednpm run bench           # token cost of the tool surfacenode scripts/versions.mjs   # every version string and pinned tag agrees (CI and the release check this)

Roadmap

Signed .mcpb releases · SSO (GitHub/Google) as an OAuth identity provider for team vaults · an optional derived SQLite index for vaults far beyond 50,000 notes · MCP Apps (an in-chat memory browser) once Claude Code ships it by default · MCP sampling, if Claude's clients ever declare it (Claude Code 2.1.302 declares only roots and elicitation, which is why consolidation and contextual retrieval still need an ANTHROPIC_API_KEY)

MIT licensed. PRs welcome.