Hypermnesia

hy·per·mne·sia n.

unusually vivid or complete memory; abnormally sharp recall of the past.

Durable, decaying memory
for your coding agents.

Hypermnesia is a local-first memory system for Claude Code, Cursor, and Google Antigravity. Editor hooks capture every session as it happens; an LLM classifies each transcript into typed memories; memories age and decay unless they keep proving useful — and the relevant ones are injected back into future sessions, so your agent remembers why the codebase is the way it is.

View on GitHub ↗ Quick start ↓ MIT · macOS 14+ · v0.1.0

The Brain MRI replay: a project's memories arranged as a brain, with pulses firing for real session events — recalls, captures, applies — while per-type counters tick up and a timeline playhead advances
The app’s live MRI view, exported as a replay — every pulse is a real event from a coding session, replayed on its wall-clock timestamp (rendered here from sample data).

01 / How it works

The loop

  1. Capture

    Hooks checkpoint the transcript during the session — capture is incremental and asynchronous, so nothing ever blocks your agent.

  2. Classify

    A pluggable LLM (Gemini by default, claude -p fallback) reads each new slice and extracts typed memories.

  3. Curate

    Confident captures go live on their own; risky writes wait as drafts for your confirm. Near-duplicates merge, and a newer memory that contradicts an older one retires it.

  4. Decay

    Memories lose confidence as they age unless use revalidates them. Staleness isn’t silent — it’s a visible, first-class state.

  5. Hydrate

    The relevant, still-trustworthy memories are injected into new sessions at start, and per-prompt by relevance — a small, bounded, confidence-gated set.

Seven types, not one blob

  • decision
  • convention
  • intent
  • fact
  • concern
  • backlog
  • code ref

Typed structure is what lets a memory carry rules like “does NOT apply to…”, applied/overridden evidence counters, and commit-pinned code references that deep-link into your editor or GitHub.

02 / Evals

Measured, honestly

3/24 → 15/24

Tasks solved when the required convention exists only in memory — a memoryless agent vs. the same agent with automatic hydration.

12/12

On the subset whose memory states the requirement explicitly, hydration matched the paste-it-into-the-prompt oracle.

17/18

Adversarial control tasks passed with memory injected — the baseline passed 18/18. Yes: injected memory broke one. The failure is committed along with everything else.

Small n · synthetic tasks · one subject model — the full harness, data, and the cases where memory hurt live in evals/RESULTS.md ↗

03 / Setup

Three clients, one memory

The same local store, captured from and injected into all three — with recall, ask, and remember available to each agent over MCP.

Claude Code

hypermnesia setup --with-mcp

One command: capture + injection hooks for all projects, plus the MCP pull path. setup --uninstall reverses everything.

Cursor

hypermnesia install-cursor-mcp
hypermnesia install-cursor-hooks

Session-start injection, stop/session-end capture, MCP tools in Cursor’s own approval UI.

Google Antigravity

hypermnesia install-antigravity-mcp
hypermnesia install-antigravity-hooks

App, IDE, and CLI variants — conversation-start injection, capture that never blocks the agent from stopping.

Any other MCP client — Claude Desktop included: { "mcpServers": { "hypermnesia": { "command": "hypermnesia", "args": ["mcp"] } } }

Don’t wait for new sessions — seed from history: hypermnesia backfill --project ~/some/repo (add --client cursor or --client antigravity)

04 / Privacy

Local-first, verifiably

05 / Install

Quick start

git clone https://github.com/tweibley/hypermnesia && cd hypermnesia
bash Scripts/make-app.sh                       # → Hypermnesia.app
swift build                                    # → .build/debug/hypermnesia

hypermnesia backfill --project ~/some/repo     # seed memory from past sessions
hypermnesia setup --with-mcp                   # hooks + recall/ask/remember
open Hypermnesia.app

Requires macOS 14+, a Swift 6 toolchain, and claude on PATH. A GEMINI_API_KEY enables the recommended classifier; without one it falls back to claude -p. hypermnesia doctor verifies the result.

06 / FAQ

Fair questions

Why not just CLAUDE.md?

Hypermnesia writes your CLAUDE.md — hypermnesia export --markdown renders a project’s confirmed memory as a committable MEMORY.md, sections, provenance, and all. The difference is everything around that file: memories decay unless they keep proving useful, carry applied/overridden evidence counters, are retired by newer contradicting captures, and are injected by relevance instead of as one ever-growing preamble. A hand-tended CLAUDE.md goes stale silently; here staleness is a first-class, visible state.

Isn’t this just RAG?

The retrieval part is deliberately boring (FTS5 + embeddings). The interesting parts sit around it: capture is automatic from real sessions; memories are typed, with structure like “does NOT apply to”; contradictions are detected at capture time; and decay + belief decide whether a memory is still trustworthy, not just similar. The evals benchmark against a paste-the-fact-into-the-prompt oracle — on explicit-memory tasks, hydration matched it.

Does injected memory ever hurt?

Measured: yes, once — memory injection broke 1 of 18 adversarial control tasks that the baseline passed (details, including the failure, in evals/). The mitigations are structural: overridden memories lose belief, stale ones fall below the injection floor until revalidated, and risky writes land as drafts you confirm before they hydrate anything.

Does it slow sessions down or eat tokens?

Hydration injects a small, bounded set: confirmed memories above a confidence floor at session start, and up to 8 relevance-ranked ones per prompt. Capture is asynchronous — hooks checkpoint and return; classification runs out-of-band, so nothing blocks the session. The only recurring spend is classification, on the model you choose.

Why macOS-only? Will there be a Linux build?

The engine and CLI are UI-free Swift over GRDB/SQLite — nothing in the capture ↔ hydrate loop is macOS-specific; the SwiftUI app is. A headless Linux build of the CLI + hooks is plausible; it just isn’t built or tested yet. If that’s what’s blocking you, open an issue.