memman
Persistent memory for Claude Code.
memman saves decisions, preferences, and project knowledge so the agent can find them in later sessions. The agent chooses what to remember and when to recall it. memman handles storage, search, and background processing.
Storing and recalling 1,000 memories costs under $1 on the default models (Cost).
Install
memman needs Python 3.11+ on Linux or macOS. The default setup uses SQLite for storage, OpenRouter for summaries, and Voyage for embeddings and reranking, so the install asks for an OpenRouter key and a Voyage key.
pipx install memman
memman install
In a terminal, memman install runs a wizard that configures the providers, saves every setting in ~/.memman/env, and installs a background worker. When it detects Claude Code, it also installs the hooks and the agent's instructions. A new Claude Code session loads them.
The worker runs as a systemd timer on Linux or a launchd agent on macOS. A host with neither sets MEMMAN_SCHEDULER_KIND=serve and runs memman scheduler serve. Installation covers headless installs and the optional Postgres backend, and Provider setup covers other providers.
Use it
The agent runs these commands through Bash, and they work the same from a shell:
memman remember "The billing service retries failed requests at most three times." --cat decision
# The background worker stores the write on its next run, every 60 seconds by default.
memman recall "billing service retry limit"
remember prints the memory's id at once, and recall finds the memory once the worker stores it. An id from remember or recall inspects or corrects a memory:
memman insights show <id>
memman replace <id> "The billing service retries batch requests four times and other requests three times."
memman insights show <id> --history
Each memory holds one self-contained claim, on one line, within 1,000 UTF-8 bytes.
| Category | Captures | Example |
|---|---|---|
preference |
User preferences and style | "Prefers explicit SQL over an ORM." |
decision |
Choices and their reasons | "The cache uses SQLite to avoid running another service." |
fact (default) |
Knowledge about systems or domains | "The billing API allows 100 requests per second." |
insight |
Conclusions drawn from evidence | "The flaky test fails only when the cache is cold." |
context |
Project or user background | "The billing service deploys to AWS ECS." |
Memory commands lists the input rules and output formats.
How it works
- The agent decides. Five lifecycle hooks remind the agent to recall context and to save its conclusions. The agent runs every memory command itself. No hook writes a memory.
- Writes enter a queue.
rememberandreplacequeue the text, and neither waits on a model. A background worker adds a short summary, creates an embedding, and stores the memory. The text is stored as written. - Recall searches stored memories. It fuses keyword matches, vector similarity, and recency, then reranks the best candidates.
recall --basicmatches words in the text instead.
A memory stays until the agent replaces or forgets it, and nothing expires on its own. A replaced memory leaves recall, and insights show --history still lists it. A forgotten memory leaves recall too.
The design guide explains the architecture and the reasons behind it.
Keep projects separate
Named stores hold separate sets of memories:
memman store create work
memman --store work recall "deployment decisions" # one command
memman store use work # the shared default
MEMMAN_STORE=work in a process's environment selects the store for that process, so two agent sessions on one host can use different stores. The --store flag wins over MEMMAN_STORE, which wins over the shared default. Store management covers per-directory selection and moving a store between SQLite and Postgres.
Cost
On the default models, 1,000 stored memories and 1,000 recalls cost under $1:
| Step | Default model | Cost |
|---|---|---|
| Summaries for 1,000 memories | qwen/qwen3-235b-a22b-2507 |
$0.40 |
| Embeddings for 1,000 memories and 1,000 queries | voyage-3-lite |
under $0.01 |
| Reranking for 1,000 recalls | rerank-3-lite |
$0.30 - $0.50 |
| Total | under $1 |
The figures rest on these assumptions:
- Summaries. 1,200 input and 100 output tokens per memory, at $0.25 in and $1.00 out per million tokens (OpenRouter pricing).
- Embeddings. Memories of 150 - 250 tokens and short queries, at $0.02 per million tokens (Voyage pricing).
- Reranking. Up to 100 candidates per recall, 150 - 250 tokens per query and memory pair, at $0.02 per million tokens. A query of two words or fewer skips reranking.
Longer memories, retries, and other providers change the total. memman bills its own API keys, and a Claude Pro or Max subscription does not cover them. Provider setup lists the key each step uses and turns reranking off.
Operate and update
memman status # memory counts for the selected store
memman scheduler status # worker state and last run
memman doctor --text # health checks, including live provider probes
The usage guide covers backups, failed writes, model changes, and configuration. A stopped scheduler refuses remember, replace, and forget, and recall keeps working.
An upgrade refreshes the installed hooks, scheduler unit, and settings when memman install runs after it:
pipx upgrade memman
memman install
Two commands remove the integration and the package:
memman uninstall
pipx uninstall memman
Uninstall keeps the stored memories, the queue, and the logs. Uninstall lists the settings it removes.
Documentation
- Usage and reference: setup, commands, configuration, and troubleshooting.
- Design and architecture: responsibilities, storage, search, and integration.
- Contributing: development setup, tests, and schema changes.
License
1 maintainer
Metadata
1 maintainer
Release files for memman 0.44.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| memman-0.44.6.tar.gz | 203.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| memman-0.44.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 437.3 kB
Release files / memman-0.44.6.tar.gz
| Download URL | memman-0.44.6.tar.gz |
|---|---|
| Size | 203.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
26e59591724193148883296e6336dc90dd3c18f3c31cc9d2a9742680e4169620
|
|
BLAKE2b-256 checksum How to use checksums |
5bf434f17aab76668b43d41bc829f34f54c4ec98032ef827a03b53379deeadbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / memman-0.44.6-py3-none-any.whl
| Download URL | memman-0.44.6-py3-none-any.whl |
|---|---|
| Size | 234.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6c5bcb3b398f9c85442d0fb8ddf71715ea653b8fbbcbadca75454c0a25e30a6e
|
|
BLAKE2b-256 checksum How to use checksums |
7d43d5c2db8b0fe5d2ccf7479c94fd4d9280dd8d0603b032d8e6de700a8a8101
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
