memnos — Memória Persistente para Agentes IA
thameema/memnos
Memória persistente e supersessão bi-temporal para agentes IA com PostgreSQL
Ver no GitHubMCP server que fornece memória persistente para agentes de IA (Claude, Cursor, Windsurf), capturando conversas e transformando-as em fatos recuperáveis entre sessões. Roda sobre PostgreSQL + pgvector, sem LLM em tempo de query, com governança integrada (autenticação, ACLs, auditoria).
Instalação
npx convez-ai thameema/memnos1 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
Casos de uso
- Manter contexto entre sessões de coding com Claude Code ou Cursor
- Construir agentes IA que aprendem e lembram de fatos ao longo do tempo
- Armazenar e recuperar conhecimento corporativo com controle de acesso
Veredito

Solução sólida e auto-hospedável para memória de agentes IA. A abordagem bi-temporal e a ausência de LLM em query-time a diferenciam, mas exige PostgreSQL e atenção ao setup. Ideal para times que precisam de persistência confiável em agentes multi-sessão.
README
A tradução para o português deste README ainda está na fila.
memnos
Your AI forgets everything between sessions. memnos fixes that.
memnos is a self-hosted memory server for AI agents. Your conversations are captured, distilled into facts, and recalled in later sessions — across Claude Code, Cursor, Windsurf, Codex, or anything that speaks MCP, REST, or an OpenAI/Anthropic-compatible base URL. It runs on one PostgreSQL + pgvector database (no second vector store, no graph database), uses no LLM at query time, and ships with governance — token auth, namespace ACLs, audit log, and an encrypted secret vault — in the open-source build.
Apache-2.0 · self-hostable · single-org · local-first · uv tool install memnos

It doesn't just remember — it knows what's true now: when a new fact contradicts an old one, bi-temporal supersession closes the old fact out, and recall shows the transition.
Quickstart
Prerequisite: PostgreSQL 13+ with the pgvector ≥ 0.7 extension. memnos does
not install Postgres — it connects to yours. No Postgres? memnos setup --docker
spins up a pgvector Postgres container for you.
Install into an isolated environment (uv recommended; pipx works too — don't
pip install into your system Python):
uv tool install memnos # no uv? brew install uv or
# curl -LsSf https://astral.sh/uv/install.sh | sh
memnos setup # enter your Postgres connection → creates schema + admin token
# (or: memnos setup --docker — needs Docker, zero Postgres setup)
memnos start # background server → open http://127.0.0.1:8900/admin
Operate it like any daemon: memnos status / stop / restart; memnos serve runs in
the foreground for systemd/launchd/Docker; memnos upgrade updates in place;
memnos autostart installs a login service so the server survives reboots.
During setup you're asked for an optional OpenAI key (stored AES-256-GCM encrypted,
never in plaintext): with one, you get 1536-d embeddings + bi-temporal fact extraction;
without one, memnos runs in free local 384-d mode — embeddings only, no extraction,
nothing leaves your machine. memnos migrate-embeddings converts between the two
losslessly if you change your mind.
Full walkthrough: QUICKSTART.md · Windows:
docs/guides/windows.md · everything else: memnos --help.
What makes it different
- It knows what's true now. Facts are bi-temporal (when it happened vs. when memnos
learned it). Single-valued facts (
lives_in,works_at) supersede on contradiction — by rule, not by asking an LLM — so "where do I live?" returns the current answer, with the old one closed out, dated, and still auditable. - One engine. Everything lives in a single PostgreSQL + pgvector — no second vector store, no graph database to run, scale, secure, or back up.
- No LLM at query time. Recall is one embedding lookup (fully on-device in local mode), hybrid search (pgvector HNSW + BM25, fused with RRF), a local ONNX cross-encoder rerank, then quota/timeline/entity guarantees. No generative call — fast, cheap, deterministic.
- Governed by default. Token auth, namespace ACLs, audit log, usage/cost ledger, server-stamped author attribution, and an encrypted secret vault with ingest redaction — in the open-source build, not an enterprise tier.
- Vendor-neutral, self-hosted. Apache-2.0, your Postgres, your data, your LLM keys (never stored in plaintext). The REST API is an OpenAPI 3.1 contract enforced in CI; the CLI is smoke-tested on Linux, macOS, and Windows on every push.
memnos is a governed memory engine, not an agent runtime. A detailed, version-pinned comparison with other memory systems lives at memnos.net/compare.
Integrations
One command wires memnos into your agent — no manual config editing:
memnos agent-setup claude-code # Claude Code: MCP + hooks (auto recall/save) + /memnos
memnos agent-setup claude-desktop # Claude Desktop
memnos agent-setup codex # Codex CLI
memnos agent-setup cursor # Cursor
memnos agent-setup windsurf # Windsurf
memnos agent-setup openclaw # OpenClaw
memnos agent-setup hermes # Hermes Agent (Nous Research)
Each mints a scoped token, is idempotent, and backs up any file it edits.
Honest capture tiers — clients differ in how reliably memory gets captured, and we'd rather tell you than pretend otherwise:
- Deterministic (Claude Code): lifecycle hooks auto-recall before each prompt and auto-save after — both your message and the assistant's reply. No model discretion.
- Deterministic (any base-URL client) —
memnos proxy: point any OpenAI- or Anthropic-compatible client at the proxy (ANTHROPIC_BASE_URL=http://127.0.0.1:8910). It relays every request untouched (streaming included, keys forwarded, never stored) and captures both sides of each completed exchange, with agent-loop noise filtered out. Guide + capability matrix. - Discretionary (everything else): MCP tools (
recall,recall_wide,remember,reconcile_claim, …) — called when the model decides to. Useful, but not guaranteed.
Also: REST (POST /remember, POST /recall — Bearer token, namespace-scoped),
CLI (memnos remember/recall), and an SDK (uv pip install memnos-sdk) with
LangChain / LangGraph / LlamaIndex adapters. Client guides:
docs/guides/clients/.
REST, MCP, hooks, and the benchmark all run the same engine — there is one codebase, not a benchmarked copy and a shipped copy.
Management console
A zero-build web console ships in the open-source build at /admin: create
namespaces, mint/revoke tokens, manage grants, view the dashboard, store secrets. Every
call is token-authenticated, namespace-ACL'd, and audited.
memnos admin # bootstrap an admin token → paste into /admin
Benchmarks (and how we report them)
LongMemEval: 78.4% on the full 500-question benchmark (gpt-4o answer + judge), run on MemoryBench — a competitor's own open harness. By category: single-session assistant facts 98.2%, user facts 92.9%, knowledge-update tracking 78.2% (with 99% retrieval Hit@10 — the engine found the answer; the answering model missed it), temporal reasoning 77.4%, multi-session 70.7%. The weak spot, disclosed: single-session preferences 46.7% (n=30) — preference statements aren't fact-shaped, and extraction underserves them today.
LoCoMo: 64–65% under the gpt-4o judge on the full benchmark (10 conversations,
1,542 QA), reproduced across three independent from-scratch ingests (the small spread
is non-deterministic extraction, not the engine). Every prediction file is published
under benchmarks/results/.
We care more about credibility than a big headline:
- Setup: full 10 conversations. Ingest → bi-temporal SPO fact extraction (gpt-4o-mini) + consolidation; retrieve via hybrid search (pgvector + BM25, RRF) + cross-encoder rerank + timeline / entity-guarantee arms — no LLM at query time; answer with the calling agent; judge with an LLM.
- Judge transparency: the score is judge-sensitive. On the same answers we measure a strict ~44% / lenient 85–88% band around the standard 64–65% — so you can see how much the judge prompt alone moves any published number.
- Independent judging: most published numbers are self-judged (the same vendor's model grades its own answers). We additionally score under an independent provider's judge (Claude grading GPT answers) to surface self-preference bias.
- On comparisons: headline numbers elsewhere are typically self-judged and sometimes on a different benchmark (e.g. DMR, not LoCoMo). We don't claim parity — we publish a reproducible harness.
Reproduce: python benchmarks/locomo_eval.py --sample-ids 0,1,2,3,4,5,6,7,8,9
(see benchmarks/).
We'd rather report a credible 64–65% with the judge ladder disclosed than an inflated 85% under a lenient one.
How it works
Claude Code ─┐
Cursor ├─ MCP (stdio) ─┐
Windsurf ─┘ │
hooks / proxy ──────────────┼─► memnos server ──► PostgreSQL + pgvector (ONE engine)
REST / CLI ─────────────────┘ ├─ hybrid retrieve: pgvector (HNSW) + BM25 (tsvector) → RRF
│ → cross-encoder rerank → quota + timeline + entity arms
│ (NO LLM at query time)
├─ bi-temporal facts + belief-change supersession
├─ governance: token auth · namespace ACL · audit · usage
└─ encrypted secret vault (AES-256-GCM) + ingest redaction
Write (LLM at ingest only): a message becomes a verbatim raw turn and structured
bi-temporal SPO facts. Near-duplicate facts are deduplicated on the write path.
Single-valued attributes supersede on change; multi-valued ones (did, visited)
accumulate. Memories can be typed, and memories typed constraint are pinned —
injected into every recall in their namespace. Secrets are redacted before storage. An
offline "sleep" pass consolidates facts into entity dossiers, and reconcile re-runs
contradiction close-out across an existing namespace.
Read (no LLM): hybrid retrieval (pgvector HNSW + BM25, RRF-fused), cross-encoder rerank, quota guarantees for raw-turn + fact coverage. Temporal questions add a guaranteed entity timeline; entity questions add an entity-guarantee arm so list/aggregation answers are complete. Recall is grounded: results carry their source namespace, and provenance links trace facts back to the turns they came from.
Security & operations
- Auth: opaque bearer tokens (SHA-256 hashed at rest; instantly revocable — not JWTs).
- ACL: every read/write is clamped to the principal's namespace grants.
- Attribution: the server stamps the authenticated principal as author — clients can't spoof it via the request body.
- Audit + usage ledger: who/what/when + per-op LLM cost.
- Secret vault: AES-256-GCM, value-refs (
secret://name), key rotation. - Redaction: secret-shaped text is stripped from remembered messages before storage.
- Health heuristic:
memnos healthturns metrics into actionable findings.
Local-first: the server binds
127.0.0.1. Put a TLS reverse proxy in front for remote use.
Status & limitations
memnos is early (0.1.x) and changing. Honest scope, so you don't find out the hard way:
- Single-org. Namespaces and ACLs within one deployment — no multi-tenant control plane in the open-source build.
- Local-first. Binds
127.0.0.1by default; remote access is your reverse proxy's job. - Text only. No image/audio/multimodal memory.
- Fact extraction needs an OpenAI key. Without one, local mode gives you embeddings + hybrid recall over verbatim turns — but no fact extraction, so no supersession or timelines.
- Capture guarantees vary by client. Deterministic only via Claude Code hooks or the proxy; plain MCP capture depends on the model choosing to call the tools (see Integrations).
- Benchmarked, not magic. 78.4% on LongMemEval (500q, full run) and 64–65% on LoCoMo under the standard judge — published with the judge ladder because those numbers move a lot depending on who grades them.
License
Apache-2.0. The open-source build is the engine + single-org self-host + the basic management console. SSO/advanced RBAC, encrypted-vault key management (KMS/HSM, rotation policies), the multi-tenant control plane, the richer enterprise UI, and managed cloud are the commercial layer.