Ultra Memory

ultra-memory

Lasting memory for Claude — on your own machine.

Claude forgets everything when a session ends. ultra-memory gives it a memory that lasts: it remembers how you work, what your project decided, and what you've learned — and keeps that knowledge tidy on its own. One Claude Code plugin, running on your machine and your Claude subscription. No cloud service, no API key, no bill.

[](LICENSE) [](.claude-plugin/plugin.json) [](pyproject.toml) [](tests/) [](https://docs.claude.com/en/docs/claude-code)

Most "memory for Claude" tools give you one bucket: they save a session, compress it, and replay it next time. ultra-memory keeps two kinds of memory at once, because not everything you want Claude to remember ages at the same speed:

• Session memory — how you work: preferences, your project's current state, corrections you've

made. Fast-moving, stored in a local SQLite database.

• A knowledge wiki — what you've learned: concepts, findings, post-mortems — the durable stuff

worth keeping. Stored as plain Markdown you can read, edit, and track in git.

When Claude needs context, ultra-memory searches both at once and returns one ranked list of what's relevant. A small graph of links ties the two together, so a lesson from a session can "graduate" into a wiki page and stay connected. And over time the plugin curates itself — merging duplicates, correcting what it got wrong, even turning repeated lessons into new reusable skills — always in small, reversible steps you can review, and never touching a rule you've locked down.

> Your data stays yours. This repository is code only — it ships no content. Your memory > database, your notes, your paths, and any secrets live in your project and are passed in by config; > nothing personal is ever committed here (a test enforces it). One plugin, many projects.

[Why](#why-ultra-memory) · [Quick start](#quick-start) · [What's different](#what-makes-it-different) · [How it works](#how-it-works) · [Comparison](#comparison) · [Configuration](#configuration) · [📖 Handbook](#-documentation--handbook) · [Status](#status--roadmap) · [Acknowledgments](#acknowledgments) · [License](#license)

---

Why ultra-memory

🧠 Two memories, searched as one. Quick "how you work" facts and a durable, growing knowledge base — kept apart because they age differently, ranked together when Claude needs them.

🔒 Private by design. Everything lives in local files. It runs on your Claude login and refuses to start if a paid API key is present — there is deliberately no metered-API path. Secrets are stripped on the way in and on the way out.

♻️ It tidies itself, safely. A background loop merges duplicates, improves what it stored, and can even create new skills from lessons it keeps seeing — in small, bounded, reversible steps. It can never delete anything (only archive it) and can never change a rule you've pinned. You read a short summary of what it did; you don't babysit it.

⚡ One-step install, then invisible. A drop-in Claude Code plugin. It adds a few milliseconds at session start and otherwise stays out of the way — and if anything ever goes wrong, it logs a line and steps aside rather than blocking your work.

---

Quick start

ultra-memory is a drop-in Claude Code plugin.

# 1. Add the marketplace
/plugin marketplace add phense/ultra-memory

# 2. Install
/plugin install ultra-memory@ultra-memory

# 3. Set up (builds the runtime, prepares the database, runs a quick check), then restart Claude Code
/ultra-memory:memory-setup

That's the whole install — no editing .mcp.json, settings.json, or any wrapper by hand. By default your memory lives in ~/.ultra-memory/memory.db, one store shared across all your projects. A few optional settings exist (see [Configuration](#configuration)), but nothing is required.

Then just use it (Claude Code namespaces a plugin's commands with the plugin name):

/ultra-memory:memory-save      save a durable fact (how you work, a decision, a reference)
/ultra-memory:memory-recall    search your memory on demand
/ultra-memory:memory-pin       keep a rule in view at the start of every session
/ultra-memory:memory-verify    reconfirm a fact is still true (resets its "stale" clock)
/ultra-memory:memory-edit      correct a stored memory
/ultra-memory:memory-inbox     apply pin/verify notes you jotted between sessions
/ultra-memory:memory-maintain  run cleanup now (no AI calls)

At the start of each session, ultra-memory injects a short summary of your pinned rules and most relevant memories. When a session ends, it saves a checkpoint. Subagents can read your memory through a read-only tool, behind a privilege boundary so they only ever see the facts they're allowed to.

Requirements: uv and git on your PATH (both checked by setup). uv provides the Python 3.13 runtime; git is how you roll back — ultra-memory commits a readable, secret-stripped snapshot of your store, and nothing else. The first setup downloads a small local search model (about the size of bge-small), cached afterward. No API key, no cloud account, ever.

---

What makes it different

Four things that, together, no other Claude-memory tool ships:

1. A real knowledge base — not just session memory

Session memory is volatile: preferences, state, corrections. But real expertise — concepts, studies, lessons learned — deserves a lasting, organized home. ultra-memory treats a Markdown knowledge wiki (plain text, versioned in git) as a first-class store alongside session memory. It ships the whole curation pipeline: it flags stale and duplicate pages, keeps links healthy, and merges near-duplicates conservatively. Every structured write goes through one gateway that files the page in the right place, removes duplicates, strips secrets, and logs the change. Want your own wiki layout? Subclass the gateway and scaffold a starter in one command:

python -m ultra_memory.wiki_gateway scaffold --out scripts/my_wiki.py --class-name MyWikiGateway --topic mytopic

Then override only the parts that differ and point wiki_gateway = "my_wiki:MyWikiGateway" at it in .ultra-memory/config.toml. Or skip the wiki entirely and run memory-only — with no wiki configured, the wiki steps simply do nothing.

2. One ranked search across both stores

A small links table records typed connections — for example, the link from a session lesson to the wiki page it grew into. A single search then blends memory and wiki results into one ranked list, scoped by a privilege boundary: a subagent can't read another project's facts or a more-trusted caller's private ones. The ranking is deterministic, so the same query gives the same order every time.

3. A self-learning loop

This is what makes it feel like an organism rather than a filing cabinet. A background loop runs in four steps: consolidate (promote lessons that have proven their worth), attribute (notice which remembered facts actually helped), self-correct (fix, retire, or set aside its own earlier notes — never your pinned rules), and synthesize (turn a cluster of related lessons into a brand-new reusable skill, after a check that it won't step on an existing one).

It's fully built and tested, and safe by construction rather than by good intentions. The rules are enforced in code, not just asked for in a prompt: it cannot touch a fact you authored or pinned, cannot delete (only archive), is capped per run (at most a few edits, a few reversions, one new skill), checkpoints to git before it acts, and writes you a summary afterward. Because every step is small and reversible, mistakes are rare and cheap to undo. You stay in the review loop, not the work loop. (See [Status](#status--roadmap) for exactly what's on by default.)

The same loop also runs a backstop that captures lessons as findable wiki pages on its own — so a fix you discover today is there to be recalled tomorrow (see below).

4. Recall-Reflex — recognise → recall → act

The whole point of a memory is to reuse it, yet most tools only fire when you've already decided to look something up. ultra-memory closes that gap from both ends — it recalls what you know the moment the situation appears, and it files away what you learn so it can be found by that same situation next time.

• Recall on the observable. Pages can carry a ## Signal — the condition in the words it actually

shows up in (an error like onnxruntime NoSuchFile … model_optimized.onnx, a market state like VIX spike + breadth collapse). When a concrete error signature lands in your prompt, a hook recalls the matching prior art and drops it straight into Claude's context — no "remember to search" required. The same one-line recall() primitive is there for any consumer to call on its own observations.

• Capture so it's findable. When a session ends, the background loop quietly turns the durable

lessons it solved — the engineering gotcha, the strategy lesson — into ## Signal-keyed wiki pages, each keyed to the observable you'd hit it by. No human in the loop, but fenced like everything else: it merges instead of duplicating, archives instead of deleting, is capped per run, and quarantines any page it can't recall back by its own signal.

This is the difference between a memory you consult and one that reaches you when it matters — it is, concretely, what stops Claude from re-deriving a fix you already solved (we built the very same one twice before this existed). On by default, with a kill-switch; the full mechanics — the recall() API, the ## Signal channel, the hook, and the graduation beat — live in the [handbook](docs/11-reference-api-schema.md#recall--the-recall-reflex-primitive).

---

How it works

        ┌───────────────────────── one knowledge base ─────────────────────────┐
        │                                                                       │
   Session memory (SQLite)                      Knowledge wiki (Markdown, in git)
   how you work · state · fixes                 concepts · studies · lessons
        │                                                                       │
        └──────────────┬──────────────  links between them  ──────────┬─────────┘
                       │                                               │
                 one ranked search  ──  blends both  ──  scoped by a privilege boundary
                       │
        one audited write path  ·  strips secrets in and out  ·  your Claude login only
                       │
   session-start summary (fast, never blocks) · end-of-session checkpoint · background cleanup

• Your Claude login only. Every AI call goes through the local claude command on your own

subscription. A paid API key on the process is a hard error — there's deliberately no metered path.

• One audited write path. Every change funnels through a single gateway that strips secrets on save

and on export, and retries safely under load.

• git is your undo button. ultra-memory commits a readable, secret-stripped snapshot of your store.

Nothing is ever hard-deleted — it's archived and redirected instead.

• It never blocks you. If a background step or a hook hits an error, it logs one line and steps

aside — it can't wedge your session.

The full story is in the [handbook](docs/README.md) — from the mental model and everyday use through configuration, building your own knowledge domain, and the engine's architecture, API, and design rationale.

---

Comparison

How ultra-memory stacks up against the most-starred AI-memory and knowledge projects — claude-mem (81k★), mem0 (58k★), Khoj (35k★), Stanford's STORM (28k★), Zep's Graphiti (27k★), and Letta / MemGPT (23k★). They lead on adoption, breadth, and hosting; ultra-memory leads on architecture — it's the only one that ships the whole stack in one Claude-native box. Every cell is marked honestly, including where the field's reach beats ours.

Legend: ✅ shipped & live · ⚠️ partial / opt-in / caveated · ❌ absent

| Capability | ultra-memory | claude-mem · 81k | mem0 · 58k | Khoj · 35k | STORM · 28k | Graphiti · 27k | Letta · 23k | |---|:--:|:--:|:--:|:--:|:--:|:--:|:--:| | Durable knowledge wiki — separate from session memory ¹ | ✅ | ❌ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | | One ranked search across memory + wiki ² | ✅ | ❌ | ⚠️ | ⚠️ | ❌ | ✅ | ❌ | | Knowledge graph / typed links | ✅ | ❌ | ⚠️ | ❌ | ⚠️ | ✅ | ❌ | | Self-learning ³ — dedup · consolidate · self-correct · synthesize | ✅ | ⚠️ | ⚠️ | ❌ | ❌ | ⚠️ | ✅ | | Audited writes + secret stripping (one gateway) | ✅ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ⚠️ | | Privilege boundary on recall | ✅ | ❌ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | | Local-first, no paid API key ⁴ | ✅ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | | Plain-text, git-trackable storage | ✅ | ⚠️ | ❌ | ❌ | ⚠️ | ❌ | ⚠️ | | Claude-Code-native, one-command install | ✅ | ✅ | ❌ | ❌ | ❌ | ⚠️ | ❌ | | Adoption / community ⁵ | ⚠️ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

¹ The durable tier is a re-queryable, accumulating knowledge wiki kept distinct from chat/session memory. STORM writes one-shot cited articles (not an accumulating base); mem0/Khoj/Graphiti/Letta persist facts, but in one LLM-extracted/graph store rather than a separately curatable wiki. ² One ranked query that fuses multiple signals in a single pass. ultra-memory's spans two tiers (the session store + the durable wiki); Graphiti fuses keyword+vector+graph in one retrieval. mem0/Khoj rank within a single memory tier; claude-mem/STORM don't blend a durable tier at all. ³ Automatic dedup + consolidate + self-correct + synthesize, behind a code-enforced safety wall. Letta earns ✅ — its self-editing memory + "sleep-time" reorganizer genuinely self-improve (the closest peer); the rest do single-step extraction/dedup. ⁴ ultra-memory has no metered path at all (your Claude OAuth login only, no key on disk). The others can run keyless (Ollama / a local model), but their default documented path uses a paid LLM/API key → ⚠️. ⁵ ultra-memory is newly public — the field's clearest edge over us. claude-mem (~81k★) and mem0 (~58k★, funded + hosted) have distribution we're still earning.

Bottom line: the big-star incumbents each nail one slice — claude-mem session capture, mem0 a portable memory layer, Graphiti the graph, Letta self-editing memory, STORM the wiki. ultra-memory is the only one that combines them in a single box: a volatile session store and a git-tracked knowledge wiki, fused into one ranked search over a typed graph, behind a single secret-stripping gateway, scoped by caller, improving itself autonomously — on your Claude login, no API key. They've earned the reach; ultra-memory has earned the architecture.

> On Hermes. ultra-memory's self-learning loop (capture → consolidate → self-correct → synthesize) is modeled on the Hermes agent's autonomous skill-Curator (~183k★). Hermes is a whole agent runtime; ultra-memory brings that same self-improving-organism pattern to the memory + knowledge layer as a plugin — so the two compose, not compete.

---

Configuration

Zero-config by default. Everything below is optional — set it at install, as an ULTRA_MEMORY_* environment variable, or in a project's .ultra-memory/config.toml:

| Setting | Default | What it does | |---|---|---| | data_db_path | ~/.ultra-memory/memory.db | Where your memory is stored. | | caller_class | subagent | Who's asking, for the recall p

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phense
• Source: phense/ultra-memory
• License: MIT

Install and usage instructions live in the source repository linked above.