memini MCP server
Commit Nov 12, 2026Provides AI agents with persistent memory using tiered storage and hybrid vector and keyword retrieval.
Also known as eleboucher/memini
- Stars
- 34
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- AGPL-3.0
What is memini MCP?
memini provides AI agents with persistent memory using tiered storage and hybrid vector and keyword retrieval.
Summary generated from the project's README
About memini MCP server
Providing AI agents with a shared, persistent memory is what memini enables for developers using MCP-capable clients like Claude Code, Cursor, or Open WebUI. It allows agents to remember and recall information through a tiered storage system that includes working, episodic, semantic, and procedural memory. The service uses hybrid retrieval, combining vector and keyword search with Reciprocal Rank Fusion to ensure high-quality results that improve as more data is collected.
Users can deploy this as a single Go binary that starts with zero configuration using an embedded SQLite file. For larger team deployments or Kubernetes environments, it scales to use Postgres with VectorChord. While an LLM is optional for background tasks like deduplication and contradiction resolution, you must provide an OpenAI-compatible embeddings endpoint. The server supports both local stdio and remote Streamable HTTP transports, making it compatible with various local and distributed agent setups.
What you can do with it
- 1Scale memory for production teamsTransition from a local laptop setup to a distributed database in a Kubernetes cluster.
- 2Improve retrieval accuracy with hybrid searchUse a combination of vector and keyword search to find relevant memories based on importance and recency.
- 3Automate memory consolidationUse an optional LLM to automatically resolve contradictions and distill episodic captures into durable facts.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MEMINI_EMBED_BASE_URLMEMINI_EMBED_DIMSMEMINI_EMBED_MODEL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableeleboucher/memini is public and reachablegithub.com/eleboucher/memini ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/eleboucher/memini ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmemini
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
memini MCP questions
What storage options does memini support?
It supports pluggable storage, including embedded sqlite-vec by default or Postgres with VectorChord for scaling.
Does memini require an LLM to function?
No, an LLM is optional. It can run headless using marker heuristics for the memory lifecycle.
How can I use memini as an MCP server?
You can use it via Remote (Streamable HTTP) at a specific host URL or via Local (stdio) using the command 'memini mcp'.
What happens if I don't configure an LLM?
Without an LLM, the system uses marker heuristics to perform the memory lifecycle, allowing durable knowledge to accumulate in an embedder-only deployment.