README
¶
memini
A shared, persistent memory service for AI agents.
memini gives any MCP-capable agent (Claude Code, Cursor, Codex, opencode, Hermes, OpenClaw, Open WebUI) one place to remember and recall, with retrieval quality that compounds over time. It runs as a single Go binary, boots with zero configuration, and scales from an embedded SQLite file on a laptop to Postgres in Kubernetes.
Documentation
| I want to... | Go to |
|---|---|
| Get it running in five minutes | Quick start, then Solo laptop |
| Self-host it for my team | Homelab and team |
| Fix bad recall | Tuning recall |
| Lay out namespaces for several agents | Multi-agent namespaces |
| Upgrade, and my server will not start | Upgrading |
| Look up a setting | Configuration |
| Look up an MCP tool, CLI command or endpoint | MCP tools, CLI, REST |
| Understand how it works under the hood | How it works |
| See a full worked example | Examples |
| Understand tiers, scopes, categories, keys | Concepts |
| See the retrieval numbers | Benchmarks |
Everything is indexed in docs/.
How it works
memini draws on three earlier projects:
- A curated, deduplicated artifact rather than a pile of chunks (after Karpathy's "LLM wiki").
- Tiered memory (working, episodic, semantic, procedural) with decay and hybrid (vector + keyword) retrieval fused with Reciprocal Rank Fusion (after
agentmemory). See docs/tiers.md for what each tier means and how memories move between them. - A stateless, K8s-native HTTP service with an opt-in LLM consolidation pipeline, per-memory TTLs, per-namespace isolation, Prometheus metrics, and an
fsckconsistency checker (aftermnemory).
Hybrid results are re-ranked by a composite of relevance, access recency, and importance rather than similarity alone, and near-duplicates are collapsed at recall time.
An LLM is optional. With one configured, writes are stored immediately and then deduplicated and contradiction-resolved in the background, and each fresh episodic capture is distilled into durable semantic facts at write time, so a fact stated once is durable immediately. Without one, marker heuristics run the same lifecycle, so durable knowledge still accumulates in an embedder-only deployment.
| Concern | Choice |
|---|---|
| Language | Go: single static binary, tiny image, low memory |
| Storage | Pluggable: sqlite-vec (embedded, default) or Postgres + VectorChord (scale) |
| Embeddings | External OpenAI-compatible endpoint (you deploy the model) |
| LLM | Opt-in: runs headless without one |
| Ranking | Hybrid (vector + keyword) RRF, re-ranked by relevance + recency + importance, deduplicated |
| Interfaces | REST + MCP (stdio and Streamable HTTP) + embedded web UI, sharing one service layer |
Quick start
memini boots with zero configuration in its embedded SQLite mode. Vector search is the one thing it cannot invent, so point it at any OpenAI-compatible embeddings endpoint:
export MEMINI_EMBED_BASE_URL=http://localhost:8081/v1
export MEMINI_EMBED_MODEL=bge-m3
export MEMINI_EMBED_DIMS=1024 # must match the model
mise run run
curl -s localhost:8080/healthz
MEMINI_EMBED_DIMS has to match the model you point at. That is the most common setup mistake, and it corrupts the store rather than failing cleanly.
For the full walk-through, including wiring it into an agent, see Solo laptop. For Docker, Compose and Kubernetes, see Deployment.
Agent plugin
Most integrations read MEMINI_BASE_URL for the server and MEMINI_API_KEY for the token. MEMINI_URL and MEMINI_TOKEN are removed: clients warn once at session start and otherwise ignore them. The Codex and Cursor plugins are the exception: their bundled MCP config uses a fixed local URL with static env-based headers; see the remote override recipe below. Where an integration has its own config (opencode options, Open WebUI Valves, openclaw.json), that config wins over the environment.
Claude Code:
/plugin marketplace add eleboucher/memini
/plugin install memini
opencode: add the plugin to opencode.json (or ~/.config/opencode/opencode.json):
{
"plugin": ["@eleboucher/opencode-memini"]
}
Hermes: hermes plugins install eleboucher/memini-hermes
OpenClaw: openclaw plugins install clawhub:@eleboucher/memini
Open WebUI: paste filter/memini_memory.py into Admin Panel, Functions, and optionally tools/memini_tools.py into Workspace, Tools.
Codex:
codex plugin marketplace add eleboucher/memini
codex plugin add memini@memini
Start the local server first (memini, default http://localhost:8080), set MEMINI_API_KEY when authentication is enabled, review and trust the bundled hooks with /hooks, then start a new thread. Remote and custom-server setup is covered in integrations/codex/.
Cursor:
ln -s "$PWD/plugin" ~/.cursor/plugins/local/memini
Reload the window (Developer: Reload Window) and confirm under Customize → Plugins; teams can instead import the repo as a marketplace (Dashboard → Plugins → Import from Repo). The bundled MCP server targets a fixed http://localhost:8080/mcp; authentication and remote setup (a ~/.cursor/mcp.json override) are covered in plugin/README.md.
Full details, edge cases and every client-side setting live in integrations/ and plugin/README.md. If a variable seems to have no effect, check server vs client variables: four names mean different things on each side.
Using it as an MCP server
memini speaks the Model Context Protocol, over two transports:
- Remote (Streamable HTTP):
http://<host>:8080/mcp - Local (stdio):
memini mcp
The nine tools an agent sees, their parameters, and the standing policy the server sends every client on connect are in MCP tools. Ready-to-paste client configs are in integrations/.
Benchmarks
memini's hybrid retrieval beats agentmemory's published LongMemEval-S numbers on the same model, dataset and metric (98.4% recall@5 against 95.2%), and reranking adds double-digit gains on the turn-level sets where base recall still has headroom.
mise run bench
Full tables, per-leg and per-category breakdowns, the tune and held-out split, parameter sweeps, methodology, caveats, and the LoCoMo comparison against mem0 and Letta are in bench/README.md.
Contributing
See CONTRIBUTING.md for the dev loop, the generated-code drift gates, and the docs conventions. The short version: the reference under docs/reference/ is generated from the code (mise run docs), and CI fails if it has drifted. If you add a setting, a CLI command or an MCP tool, run mise run docs and commit the result. The generator refuses to run when a new setting has no doc comment or belongs to no section, which is deliberate: that is how a knob ships undocumented.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bench is a retrieval benchmark harness: it ingests a dataset of memories and scores each question's gold retrieval (Recall@K, MRR) and latency.
|
Package bench is a retrieval benchmark harness: it ingests a dataset of memories and scores each question's gold retrieval (Recall@K, MRR) and latency. |
|
cmd
|
|
|
bench
command
|
|
|
gendocs
command
Command gendocs renders docs/reference/configuration.md from the source of truth: the env-tagged fields on config.Config, their doc comments, and the deprecatedVars table.
|
Command gendocs renders docs/reference/configuration.md from the source of truth: the env-tagged fields on config.Config, their doc comments, and the deprecatedVars table. |
|
memini
command
|
|
|
qa
command
Command qa measures end-to-end QA accuracy (LLM-judged) over a benchmark conversation corpus: ingest into memini (direct upserts or the production write path), answer each question with the shipped service.Answer, and grade against the reference with per-category judge rubrics.
|
Command qa measures end-to-end QA accuracy (LLM-judged) over a benchmark conversation corpus: ingest into memini (direct upserts or the production write path), answer each question with the shipped service.Answer, and grade against the reference with per-category judge rubrics. |
|
internal
|
|
|
api/mcp
Package mcp exposes memini over the Model Context Protocol.
|
Package mcp exposes memini over the Model Context Protocol. |
|
api/render
Package render holds the shared response-projection helpers for memini's API surfaces (REST and MCP): concise content rendering for progressive disclosure, compact display titles, and the content-identity hash clients use for injection dedupe.
|
Package render holds the shared response-projection helpers for memini's API surfaces (REST and MCP): concise content rendering for progressive disclosure, compact display titles, and the content-identity hash clients use for injection dedupe. |
|
api/rest
Package rest provides primitives to interact with the openapi HTTP API.
|
Package rest provides primitives to interact with the openapi HTTP API. |
|
api/ui
Package ui serves memini's embedded single-page admin UI (Preact + Vite).
|
Package ui serves memini's embedded single-page admin UI (Preact + Vite). |
|
apiauth
Package apiauth resolves the bearer-token principal for a request.
|
Package apiauth resolves the bearer-token principal for a request. |
|
chunk
Package chunk splits long memory content into overlapping segments for embedding, so a memory stays searchable past the single-vector budget.
|
Package chunk splits long memory content into overlapping segments for embedding, so a memory stays searchable past the single-vector budget. |
|
contradict
Package contradict classifies a pair of durable memory texts without an LLM: is the new write a restatement of the old fact (corroborate it), an update that contradicts it (the old fact is now stale), or a distinct claim (do nothing)? Embedding similarity cannot make this call — a value swap ("TTL is 10 minutes" → "TTL is 15 minutes") embeds in the same band as a restatement (measured in bench/dedup_test.go) — so this is a lexical differ in the tradition of de Marneffe et al.
|
Package contradict classifies a pair of durable memory texts without an LLM: is the new write a restatement of the old fact (corroborate it), an update that contradicts it (the old fact is now stale), or a distinct claim (do nothing)? Embedding similarity cannot make this call — a value swap ("TTL is 10 minutes" → "TTL is 15 minutes") embeds in the same band as a restatement (measured in bench/dedup_test.go) — so this is a lexical differ in the tradition of de Marneffe et al. |
|
embed
Package embed turns text into dense vectors via an external, OpenAI-compatible embeddings endpoint; memini never embeds locally.
|
Package embed turns text into dense vectors via an external, OpenAI-compatible embeddings endpoint; memini never embeds locally. |
|
extract
Package extract distils conversation prose into durable, classified facts without an LLM — a port of mempalace's heuristic extractor.
|
Package extract distils conversation prose into durable, classified facts without an LLM — a port of mempalace's heuristic extractor. |
|
httputil
Package httputil holds tiny HTTP helpers shared across the REST and /healthz handlers.
|
Package httputil holds tiny HTTP helpers shared across the REST and /healthz handlers. |
|
importer
Package importer bulk-loads memories exported from other memory systems (agentmemory, mem0, mnemory) or memini's own format.
|
Package importer bulk-loads memories exported from other memory systems (agentmemory, mem0, mnemory) or memini's own format. |
|
llm
Package llm holds the opt-in consolidation pipeline: on each write it decides whether a new memory is novel, a refinement, or a contradiction that supersedes an existing one.
|
Package llm holds the opt-in consolidation pipeline: on each write it decides whether a new memory is novel, a refinement, or a contradiction that supersedes an existing one. |
|
logging
Package logging builds the application's slog logger from config.
|
Package logging builds the application's slog logger from config. |
|
maintenance
Package maintenance keeps the store healthy: a background sweeper purges expired memories and bounds short-term capacity, and fsck additionally audits live memories for duplicate (poisoning) clusters.
|
Package maintenance keeps the store healthy: a background sweeper purges expired memories and bounds short-term capacity, and fsck additionally audits live memories for duplicate (poisoning) clusters. |
|
memory
Package memory defines memini's core domain types.
|
Package memory defines memini's core domain types. |
|
nsresolve
Package nsresolve is the transport-free namespace-resolution core behind the config-handshake redesign.
|
Package nsresolve is the transport-free namespace-resolution core behind the config-handshake redesign. |
|
redact
Package redact scrubs live credentials from text before it is persisted.
|
Package redact scrubs live credentials from text before it is persisted. |
|
rerank
Package rerank holds the optional read-side rerank stage of recall: after hybrid retrieval and composite ranking, a reranker reads the query and the candidates together — something embeddings can't — and reorders them by how well each answers the query.
|
Package rerank holds the optional read-side rerank stage of recall: after hybrid retrieval and composite ranking, a reranker reads the query and the candidates together — something embeddings can't — and reorders them by how well each answers the query. |
|
sanitize
Package sanitize provides write-path content hygiene for memini: stripping unambiguous corruption (always-on) and detecting "script-salad" garble (opt-in).
|
Package sanitize provides write-path content hygiene for memini: stripping unambiguous corruption (always-on) and detecting "script-salad" garble (opt-in). |
|
search
Package search fuses results from multiple retrieval strategies (vector, keyword) into a single ranking, via either Reciprocal Rank Fusion (Fuse) or convex-combination score fusion (FuseScores), then re-ranks the result.
|
Package search fuses results from multiple retrieval strategies (vector, keyword) into a single ranking, via either Reciprocal Rank Fusion (Fuse) or convex-combination score fusion (FuseScores), then re-ranks the result. |
|
server
Package server wires the HTTP surface: middleware, health probes, metrics, graceful shutdown, and a chi router that other packages mount routes onto.
|
Package server wires the HTTP surface: middleware, health probes, metrics, graceful shutdown, and a chi router that other packages mount routes onto. |
|
store
Package store defines the storage abstraction memini retrieves memories through.
|
Package store defines the storage abstraction memini retrieves memories through. |
|
version
Package version exposes build metadata, injected via -ldflags at build time.
|
Package version exposes build metadata, injected via -ldflags at build time. |