convez.ai
MCP Server
eleboucher

memini

eleboucher/memini

Ver no GitHub
InicialPluginScore · de 0 a 100

Give any MCP-capable agent persistent memory: remember/recall over a tiered store with hybrid vector + keyword retrieval. Single Go binary, SQLite or Postgres, embedded admin UI.

Instalação

$npx convez-ai eleboucher/memini

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
34
Forks
9
Acompanhando
1
Saúde
42%
Último commit
há 2 dias
Versão
—
Issues abertas
5
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

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

ConcernChoice
LanguageGo — single static binary, tiny image, low memory
StoragePluggable: sqlite-vec (embedded, default) or Postgres + VectorChord (scale)
EmbeddingsExternal OpenAI-compatible endpoint (you deploy the model)
LLMOpt-in — runs headless without one; enables background dedup, consolidation, and episodic→semantic promotion when configured
RankingHybrid (vector + keyword) RRF, re-ranked by relevance + recency + importance, deduplicated
InterfacesREST (OpenAPI) + MCP (stdio & Streamable HTTP) + embedded web UI, sharing one service layer

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

Configuration (12-factor)

Env varDefaultDescription
MEMINI_HTTP_ADDR:8080HTTP listen address
MEMINI_BACKENDsqlitesqlite or postgres
MEMINI_SQLITE_PATHmemini.dbsqlite database path
MEMINI_POSTGRES_DSN—required when MEMINI_BACKEND=postgres
MEMINI_EMBED_BASE_URL—OpenAI-compatible embeddings endpoint
MEMINI_EMBED_MODELtext-embedding-3-smallembedding model name
MEMINI_EMBED_DIMS1536embedding dimensions (must match model)
MEMINI_EMBED_QUERY_PREFIX—instruction prepended to recall queries before embedding, for instruction-tuned asymmetric embedders (documents stay bare). For Qwen3-Embedding: Instruct: Given a user query, retrieve relevant memories that answer it\nQuery:
MEMINI_FUSION_ALPHA0.5hybrid fusion: convex score-fusion weight on the vector leg (0.5 balanced; higher favors vector, lower favors keyword). A negative value falls back to rank fusion (RRF).
MEMINI_WRITE_DEDUP_MIN_SCORE0non-LLM corpus hygiene: coalesce a fresh write into an existing same-tier memory at or above this vector similarity instead of storing a near-duplicate (only when LLM consolidation isn't handling the write). 0 disables; ~0.9 collapses near-identical restatements only (embedder-dependent).
MEMINI_LLM_BASE_URL—opt-in LLM endpoint; empty disables it
MEMINI_LLM_APIopenaichat backend: openai or anthropic (e.g. MiniMax)
MEMINI_LLM_MODELgpt-4o-miniconsolidation model name
MEMINI_CONSOLIDATE_MODEasyncasync (store now, dedup in background), sync, or off
MEMINI_CONSOLIDATE_MIN_SCORE0.6similarity gate: skip the LLM when the nearest candidate scores below it (0 disables)
MEMINI_PROMOTE_INTERVAL24hhow often frequently-used episodic memories are distilled into semantic facts (0 disables; needs LLM)
MEMINI_PROMOTE_MIN_ACCESS3minimum recall count before an episodic memory is eligible for promotion
MEMINI_API_KEY—if set, required as a bearer token (also gates /metrics)
MEMINI_UI_ENABLEDtruemount the embedded admin UI at / (false for a headless API/MCP-only service)
MEMINI_NAMESPACE_HEADERX-Memini-Namespaceheader used to scope tenants
MEMINI_DEFAULT_NAMESPACEautofallback namespace (see Namespace resolution)
MEMINI_LOG_LEVELinfodebug/info/warn/error
MEMINI_LOG_FORMATjsonjson or text

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.

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/; rebuild 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 is committed under internal/api/ui/dist/, so a plain go build always embeds a working UI.

MCP

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

  • 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, or memini's own format, 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

Each source's fields map onto memini's tiers (e.g. agentmemory workflow→procedural, mem0 facts→semantic) and namespace (project/user_id). 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 -.

Benchmark

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

On the full 500-question LongMemEval-S (recall_any@K), memini hybrid beats agentmemory on the same embedding model (all-MiniLM-L6-v2, 384-d) — a true apples-to-apples head-to-head — and goes higher with a premium model:

SystemEmbeddingR@5R@10
memini — hybrid (RRF)all-MiniLM-L6-v296.8%98.6%
memini — hybrid (RRF)Qwen3-Embedding-8B97.6%98.4%
agentmemory — BM25+Vectorall-MiniLM-L6-v295.2%98.6%
agentmemory — BM25-only—86.2%94.6%

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

License

AGPL-3.0.

Ver o original no GitHub

Bom para

Relacionados