memini

memini

A shared, persistent memory service for AI agents.

memini gives any MCP-capable agent (Claude Code, opencode, Codex, 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 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 fsck consistency checker (after mnemory).

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.