# Ultra Memory

> Lasting memory for Claude Code — session memory + a git-tracked knowledge wiki, searched as one, with a self-learning loop. Local-first, OAuth-only, no API key.

- **Type:** MCP server
- **Install:** `agentstack add mcp-phense-ultra-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [phense](https://agentstack.voostack.com/s/phense)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [phense](https://github.com/phense)
- **Source:** https://github.com/phense/ultra-memory

## Install

```sh
agentstack add mcp-phense-ultra-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://docs.claude.com/en/docs/claude-code) plugin.

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

```text
/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](https://github.com/thedotmack/claude-mem) (81k★), [mem0](https://github.com/mem0ai/mem0) (58k★), [Khoj](https://github.com/khoj-ai/khoj) (35k★), Stanford's [STORM](https://github.com/stanford-oval/storm) (28k★), Zep's [Graphiti](https://github.com/getzep/graphiti) (27k★), and [Letta / MemGPT](https://github.com/letta-ai/letta) (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](https://github.com/NousResearch/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](https://github.com/phense)
- **Source:** [phense/ultra-memory](https://github.com/phense/ultra-memory)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-phense-ultra-memory
- Seller: https://agentstack.voostack.com/s/phense
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.