memman

LLM-supervised persistent memory for coding agents.

Memory categories

See Design & Architecture for details.

How it works

The coding agent runs Memman. Claude Code hooks remind the agent to recall at session start, on each prompt, and before a delegation, and to store its conclusions when it leaves plan mode.

Five hook scripts respond to Claude Code events:

Inside Claude Code vs outside

During a turn, the agent queues writes and recalls stored memories. A background worker enriches queued writes and creates their embeddings.

 Inside the turn                          Background worker
+----------------------------------+     +-----------------------------------+
| memman remember                  |     | a drain runs every 60 s (default) |
|   append the write to queue.db --+---->|   claim each queued write         |
|                                  |     |   enrich it with the LLM          |
| memman recall                    |     |   embed it                        |
|   read the store <---------------+-----+-- store the memory                |
|   embed the query, rerank        |     |                                   |
+----------------------------------+     +-----------------------------------+

This split determines when model calls run and when memories become available:

• Model calls. The agent's turn never enriches or embeds a write. remember appends to the queue and makes no network call. recall reads the local store and, on its default path, embeds the query and reranks the top results. --basic makes neither call. Opening a store needs the Voyage or OpenRouter key when either provider is in use, including with --basic (Where keys are needed).
• Recallable after a drain. A queued write is not recallable until a drain stores it. After that, recall returns it in the same session or any later one.

Features

• Built for coding agents - stores decisions, preferences, and facts from one Claude Code session for recall in later sessions.
• Recall reminders - five lifecycle hooks remind the agent to recall and to store.
• LLM-supervised - the host LLM decides what to remember and forget. A worker model handles enrichment. No LLM judges a write.
• Combined search rankings - Reciprocal Rank Fusion (RRF) combines keyword, vector, and recency rankings. A reranker reorders the top results of a query longer than two words.
• Explicit replacements - a write adds a row or replaces the row named by replace <id>. Only replace and supersede retire a row. A retired row keeps its content and records its successor in superseded_by. Recall skips it. memman insights show <id> --history shows the chain of replacements.
• Nothing expires - a store has no size cap, and nothing expires or is pruned on its own. memman forget <id> is the only command that removes a single memory. memman insights review flags temporary information to help with that decision.
• Embedding providers - the registered providers are voyage, openai (any OpenAI-compatible endpoint), openrouter, and ollama. Each store's meta.embed_fingerprint binds it to one model, so one process serves stores on different models. memman embed swap and memman embed reembed move stores to a new model (Embedding operations).
• Storage options - SQLite by default. The memman[postgres] extra adds Postgres with pgvector, and memman migrate moves a store between the two in one command (Usage).
• External scheduled backups - memman backup schedule '<cron>' <dir> writes every store to an outside directory on a cron schedule and keeps the last N bundles. Bundles leave out secrets. memman backup restore rebuilds a working store after the loss of ~/.memman/ (Backup).

Install

pipx install memman
# or, with the optional Postgres backend:
# pipx install 'memman[postgres]'
memman install

In a terminal, memman install runs a wizard. It asks for the LLM endpoint, the embedding provider, the keys those two need, and the storage backend. It asks for the reranker's Voyage key only when Voyage embeddings were chosen (Reranker). A loopback LLM endpoint (Ollama, local vLLM or LiteLLM) may leave the API key blank. A headless install passes --no-wizard and takes the keys from the shell or from an existing ~/.memman/env. Variable reference lists every key.

Installation creates or updates these paths:

The install needs systemd on Linux, launchd on macOS, or MEMMAN_SCHEDULER_KIND=serve on a host that runs memman scheduler serve itself. It installs into ~/.claude when it detects Claude Code, and installs only the scheduler when it does not. --target skips the detection:

memman install --target claude-code

A new Claude Code session picks up the hooks. Development covers editable installs and the test suite.

Provider setup

memman calls three outside services: an LLM for enrichment, an embedding provider for vector search, and a reranker that orders recall results.

Where keys are needed

• Opening a store builds two embedding clients. One is for MEMMAN_EMBED_PROVIDER. The other is for the provider the store's fingerprint names. The voyage and openrouter clients refuse to start without their key. The openai client starts without a key, and its first embedding call fails.
• Every key lives in ~/.memman/env. memman reads its settings from that file and ignores the shell. memman config set KEY VALUE writes a key (Configuration).
• Reranking uses a Voyage key whatever the embedding provider is. Voyage is the only reranker, and reranking is on by default. memman config set MEMMAN_RERANK_ENABLED false turns it off. MEMMAN_RERANK_ENABLED_<store> sets it for one store. This is the one key whose absence degrades recall instead of stopping it.

LLM providers

The LLM client uses the OpenAI-compatible /chat/completions protocol. Any endpoint that supports it works without code changes.

Switching endpoints takes three settings, because the default model ID is an OpenRouter ID:

memman config set MEMMAN_LLM_ENDPOINT https://api.openai.com/v1
memman config set MEMMAN_LLM_API_KEY sk-...
memman config set MEMMAN_LLM_MODEL <model id>

MEMMAN_LLM_MODEL names the model, and memman never changes it on its own. On OpenRouter, the install sets qwen/qwen3-235b-a22b-2507, and each request routes only to the vendors in MEMMAN_LLM_PROVIDER_ONLY under zero data retention (LLM routing). memman checks at install, and once a day from the scheduler, that such a vendor serves the model and that OpenRouter lists no retirement date for it. A failed check prints a notice at session start that names the fix. On any other endpoint the wizard asks for a model id, and an install without the wizard refuses to finish without one.

Embedding providers

Each store records the provider, model, and vector dimension of its embeddings in meta.embed_fingerprint. One process can therefore serve stores bound to different providers.

The wizard and --embed-provider offer voyage, openai, and openrouter. ollama is set only with memman config set MEMMAN_EMBED_PROVIDER ollama.

A store stays bound to the model its fingerprint records. A change of MEMMAN_EMBED_PROVIDER reaches a store only after memman embed reembed rewrites every SQLite store, or memman embed swap moves one store. Both need a stopped scheduler (Embedding operations):

memman config set MEMMAN_EMBED_PROVIDER openai
memman config set MEMMAN_OPENAI_EMBED_API_KEY sk-...
memman scheduler stop
memman embed reembed
memman scheduler start

Reranker

memman includes one reranker, enabled by default. It scores the top recall results against the query so the best match comes first.

Operation

Memory shared across sessions

Every session uses the default store until another is chosen, so a decision remembered in one session is recalled in every later one.

Isolation per project or agent

Named stores keep memories apart:

memman store create work                  # create a store
memman store use work                     # make it the active store
memman --store work recall "query"        # one command
MEMMAN_STORE=work memman recall "query"   # one process

--store takes precedence over MEMMAN_STORE, which takes precedence over the active store.

Automatic store selection per directory

A tool that loads environment variables for each directory, such as direnv, sets MEMMAN_STORE per project:

cd ~/projects/work
echo 'export MEMMAN_STORE=work' > .envrc
direnv allow

Every shell, agent, and subprocess started in that directory uses the work store. USAGE.md compares the alternatives.

Customizing behavior

The included guide.md (instructions for the agent) and SKILL.md (full manual) live inside the installed package. A change to either belongs in the package source. An editable install (pipx install -e .) uses the edited files immediately.

What memman remember does

memman remember appends a row to queue.db and returns. It refuses text over 1,000 bytes, text that spans lines, and other text that fails the single-memory format checks (What remember and replace refuse). The scheduler drains every 60 s by default (memman scheduler interval changes it), and a write becomes recallable once a drain stores it (Inside Claude Code vs outside).

Pausing the scheduler

memman scheduler stop sets the state to stopped and disables the systemd timer or launchd agent. While stopped, memman is recall-only: remember, replace, supersede, unsupersede, and forget report that the scheduler is stopped and writes are disabled. scheduler trigger reports the same error. graph rebuild, embed reembed, and embed swap run only while the scheduler is stopped. memman scheduler start resumes it (Scheduler).

Updating

pipx upgrade memman

Upgrading updates the hook scripts and SKILL.md through their symlinks into the installed package. It also updates guide.md, which memman prime reads from the package. Run memman install after each upgrade to update the following files and settings:

• ~/.claude/settings.json. It holds the hook registrations and the allow entries. A release that adds or removes a hook or changes its matcher keeps the old registration until memman install rewrites the file. memman doctor reports a registration that differs from what install writes.
• The scheduler unit. A release that changes the unit takes effect only when memman install rewrites it.
• New settings. A release that adds a setting writes its default to ~/.memman/env only at install. memman doctor reports a missing key.

Uninstall

memman uninstall            # remove hooks, skill, settings entries, scheduler unit
pipx uninstall memman       # remove the memman binary

Either command runs alone. memman uninstall also removes a scheduled backup and deletes the API keys and the default Postgres DSN from ~/.memman/env. It keeps every store, the logs, and the other settings. Usage lists what it removes.

Development

make dev            # editable Poetry install with dev dependencies
make test           # unit tests (pytest)
make e2e            # end-to-end tests
pipx install -e .   # editable pipx install, for the Claude Code integration
memman install      # deploy the integration
memman uninstall    # remove the integration

Dependencies: Python 3.11+, Click, httpx, tqdm, numpy. The postgres extra adds psycopg, psycopg-pool, and pgvector. Where keys are needed lists the keys. CONTRIBUTING.md covers setup, tests, and conventions.

Documentation

• Design & Architecture: the design chapters, from background to Claude Code integration
• Usage & Reference: every command, flag, and setting
• Contributing: development setup, schema changes, and tests
• Diagrams: the LLM-supervised split, system architecture, memory data model, remember pipeline, recall pipeline, and Claude Code integration

License

MIT