memini

memini

A memory service for AI agents. memini gives any MCP-capable agent — Claude Code, opencode, Codex, Hermes, OpenClaw — a shared, persistent place to remember and recall, with retrieval quality that compounds over time.

It synthesizes three ideas:

• 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).
• A stateless, K8s-native HTTP service with an opt-in LLM consolidation pipeline, per-memory TTLs, per-tenant isolation, Prometheus metrics, and an fsck consistency checker (after mnemory).

Retrieval is tuned for quality-per-byte: hybrid results are re-ranked by a composite of relevance, access recency, and importance (not similarity alone), and near-duplicates are collapsed at recall time. When an LLM is configured, writes are stored immediately and deduplicated/contradiction-resolved in the background (a similarity gate skips the LLM when nothing close exists), and frequently-recalled episodic memories are periodically distilled into durable semantic facts so retrieval quality compounds over time.

Design at a glance

Running

memini boots with zero configuration in its embedded (sqlite) mode — but vector search needs an embeddings endpoint:

export MEMINI_EMBED_BASE_URL=http://localhost:8081/v1   # any OpenAI-compatible embeddings API
export MEMINI_EMBED_MODEL=bge-m3
export MEMINI_EMBED_DIMS=1024
mise run run
curl -s localhost:8080/healthz

Docker Compose (full local stack)

compose.yaml brings up everything you need to try memini on a laptop — Postgres + VectorChord, a CPU embeddings server (text-embeddings-inference serving bge-small-en-v1.5, 384-d), and memini itself wired to both:

docker compose up --build      # builds the image, starts db + embeddings + memini
curl -s localhost:8080/healthz # -> ok, once the db healthcheck passes
open http://localhost:8080/    # embedded admin UI

memini is reachable at http://localhost:8080 (REST + MCP + UI). To enable the opt-in LLM pipeline (background dedup/consolidation, /v1/answer, llm rerank), uncomment MEMINI_LLM_BASE_URL/MEMINI_LLM_MODEL in the memini service and point them at any OpenAI-compatible chat endpoint. docker compose down -v tears it down and drops the Postgres volume.

A single container (sqlite mode)

For a self-contained server with no Postgres, run the image in its default embedded (sqlite) mode — just give it a volume for the database and an embeddings endpoint to talk to:

docker build -t memini .       # or use a prebuilt image if you publish one
docker run --rm -p 8080:8080 \
  -v memini-data:/data \
  -e MEMINI_SQLITE_PATH=/data/memini.db \
  -e MEMINI_EMBED_BASE_URL=http://host.docker.internal:8081/v1 \
  -e MEMINI_EMBED_MODEL=bge-small-en-v1.5 \
  -e MEMINI_EMBED_DIMS=384 \
  memini

The image runs as a non-root user (65532); the named volume keeps memories across restarts. On Linux, swap host.docker.internal for the host IP (or add --add-host=host.docker.internal:host-gateway) to reach an embeddings server running on the host.

As an MCP server in Docker

The same image serves MCP. For a shared, always-on server, run it over HTTP (the Compose or single-container setups above already expose /mcp at http://localhost:8080/mcp) and point agents at that URL.

For a stdio MCP server the agent spawns per session, run memini mcp in the container with -i (keep stdin open) and no published port:

docker run -i --rm \
  -v memini-data:/data \
  -e MEMINI_SQLITE_PATH=/data/memini.db \
  -e MEMINI_EMBED_BASE_URL=http://host.docker.internal:8081/v1 \
  -e MEMINI_EMBED_MODEL=bge-small-en-v1.5 -e MEMINI_EMBED_DIMS=384 \
  memini mcp

Wire that into any MCP client as the launch command — e.g. for Claude Code / opencode:

{
  "mcpServers": {
    "memini": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "memini-data:/data",
        "-e",
        "MEMINI_SQLITE_PATH=/data/memini.db",
        "-e",
        "MEMINI_EMBED_BASE_URL=http://host.docker.internal:8081/v1",
        "-e",
        "MEMINI_EMBED_MODEL=bge-small-en-v1.5",
        "-e",
        "MEMINI_EMBED_DIMS=384",
        "memini",
        "mcp"
      ]
    }
  }
}

This works as-is — memory lands in the default namespace. A detached container can't auto-detect the agent's repo the way the plugin does, so if you want per-project isolation set MEMINI_DEFAULT_NAMESPACE (or pass a namespace argument per tool call). See integrations/ for per-agent recipes and the shared-namespace trick.

Configuration (12-factor)

Namespace resolution

A request's namespace is taken from X-Memini-Namespace (configurable via MEMINI_NAMESPACE_HEADER). The authoritative source of that header is the plugin/ — each hook script resolves the namespace from the agent's working directory via git rev-parse --show-toplevel and sends it on every call. That is what makes HTTP mode "just work" across projects without per-project config.

When the header is absent — for example on a stdio MCP launch without the plugin, or an HTTP call that forgot to set it — the server falls back to the same resolver at startup time, in this order:

1. MEMINI_DEFAULT_NAMESPACE (or MEMINI_NAMESPACE) env var, if non-empty.
2. git rev-parse --show-toplevel in the server's cwd — uses the repo basename, e.g. memini for /home/dev/memini.
3. basename(cwd) if the cwd is not inside a git worktree.
4. Literal default as a last resort.

The resolved value and its source (env / git / cwd / fallback) are logged at startup, e.g.:

{"level":"INFO","msg":"starting memini","default_namespace":"memini","namespace_source":"git",...}

In HTTP mode, the server-side auto-resolve is misleading: the server runs detached from the agent's cwd, so the resolved basename reflects the server's project, not the agent's. Install the plugin (or send the header explicitly per request) to get the right namespace. In stdio mode the server inherits the agent's cwd, so the fallback is correct.

Web UI

memini ships an embedded admin UI (Preact + Vite, compiled into the binary) served at /. It needs no separate process — open http://localhost:8080/.

• Overview — per-namespace stats and a tier "strata" bar (working → episodic → semantic → procedural).
• Browser — paginated, tier/expired/superseded-filterable list with a detail drawer and delete.
• Search — hybrid recall with relevance scores.
• Graph — D3 force-directed view; edges are supersession (directed) and shared-tag affinity.
• Health — runs fsck and surfaces duplicate clusters.

Use the namespace switcher (top bar) to change tenant, and Settings to set a bearer token (sent as Authorization: Bearer …) or point the UI at a remote memini. The static shell is unauthenticated so you can enter a token; the /v1 API it calls still enforces MEMINI_API_KEY. Disable the whole thing with MEMINI_UI_ENABLED=false.

[!WARNING] When MEMINI_API_KEY is set, the server embeds the key in the UI shell so the same-origin UI authenticates without pasting it — which means anyone who can load / can read the key. Only expose the UI where reaching it already implies trust, or set MEMINI_UI_ENABLED=false on untrusted networks.

It is backed by three read-only endpoints alongside the core API: GET /v1/memories (list with tier/include_expired/include_superseded/limit filters), GET /v1/stats, and GET /v1/namespaces.

The UI sources live in ui/; build the embedded bundle with mise run ui (or iterate with HMR via mise run ui-dev, which proxies /v1 to a local server on :8080). The built bundle under internal/api/ui/dist/ is a gitignored build artifact: the Docker image builds it, while a plain go build without it still works and serves a placeholder page.

Answering

Beyond raw recall, POST /v1/answer {query, limit} retrieves memories and has the LLM generate a grounded answer from them, returning the answer plus the supporting sources (requires an LLM; also exposed as the memory_answer MCP tool).

Reranking — which recall config to use

MEMINI_RERANK adds an optional read-side rerank over the hybrid candidates (off, a cross-encoder /rerank URL served by Infinity / vLLM / llama-server --rerank, or llm). See the full benchmark table for measured numbers across every config and dataset. Two rules of thumb:

• Reranking only helps where base recall has headroom. On session-level sets hybrid is already at ~98–99% — reranking is a no-op. On turn-level LoCoMo (gold = exact turns) it pays off big: +11pp R@5 / +17pp MRR (cross-encoder) or +15pp / +25pp (LLM).
• The cross-encoder is the better default when you need it: most of the LLM's lift at a fraction of the latency, a tiny 0.6B model, and no chat dependency. Use llm only if you already run a chat model and want the last few points.

MCP

memini speaks the Model Context Protocol so agents can remember/recall/answer:

• Remote (Streamable HTTP): http://<host>:8080/mcp
• Local (stdio): memini mcp

Ready-to-paste configs for Claude Code, opencode, Codex, Hermes, and OpenClaw — plus the shared cross-agent namespace trick — live in integrations/. For Claude Code and Codex, prefer the plugin/ which auto-captures tool calls and injects prior context at session start.

Importing

memini import loads an export from agentmemory, mem0, mnemory, memini's own format, or your Claude Code session history, into the local store or a running server.

# Local store (embeds + preserves source IDs, timestamps, tiers):
memini import --source agentmemory ./agentmemory-export.json

# Remote server over REST:
memini import --source mem0 --remote https://memini.example.com \
  --token "$MEMINI_API_KEY" --namespace my-project ./mem0-export.json

# Backfill Claude Code history: each user→assistant exchange becomes one
# episodic memory, scoped to the project namespace (the transcript's cwd
# basename). Accepts a single transcript, a project dir, or all projects:
memini import --source claude-code ~/.claude/projects

The claude-code source reconstructs verbatim exchanges from session transcripts (~/.claude/projects/<project>/<session>.jsonl), skipping tool-result noise, sidechains, and slash-command wrappers. IDs are deterministic, so re-importing is idempotent. Backfilled memories get a fresh 90-day episodic TTL (so old history isn't swept on arrival) while keeping the original timestamp for recency ranking. This pairs with the plugin's auto-capture: backfill once, then the hooks keep it current.

Each source's fields map onto memini's tiers (e.g. agentmemory workflow→procedural, mem0 facts→semantic) and namespace (project/user_id). Records whose source carries no recognized tier default to episodic (90-day TTL), so a bulk import of unknown quality ages out unless recall reinforces it rather than living forever as durable facts. Empty records are skipped; per-record failures don't abort the run. Over --remote the server sets its own timestamps, so the source's created-at is kept in metadata.imported_created_at. Reads stdin when the path is -.

For low-quality bulk exports, two optional gates drop weak records before they're written (both off by default):

# Skip stubs shorter than 40 bytes and anything below importance 0.3:
memini import --source mem0 --min-length 40 --min-importance 0.3 ./export.json

Note --min-importance skips records whose source reported no importance (they arrive as 0); leave it off unless your export carries real importance scores.

Benchmark

mise run bench   # offline retrieval benchmark (hybrid vs vector vs keyword)

Full results from a bench/results/ run (written locally; gitignored), all on the same all-MiniLM-L6-v2 (384-d) endpoint — the model agentmemory benchmarks with. Cells are recall_any@5 / @10 / MRR (%); p50 is in-process recall latency (rerank rows show the cost they add on top):

Questions: LongMemEval 500, LoCoMo turn 1,982, LoCoMo session 1,981 (rerank = Qwen3-Reranker-0.6B cross-encoder, Qwen3.5-9B LLM). Hybrid never trails either single leg on the saturated session sets; on turn-level LoCoMo (gold = exact evidence turns) base recall has headroom, so reranking pays off big — cross-encoder +11pp R@5 / +17pp MRR, LLM +15pp / +25pp — while being a no-op once recall is already at ceiling.

On the same model, dataset, and metric, memini hybrid beats agentmemory's published LongMemEval-S numbers, and goes higher with a premium embedder:

memini's Porter-stemming keyword leg is +11pp over their BM25-only. Full per-leg/per-category tables, parameter sweeps, methodology, caveats, and the LoCoMo QA comparison (vs mem0/Letta) are in bench/.

License

AGPL-3.0.