memgres

Versioned document memory for AI agents — one Postgres, lexical or semantic recall, diff-based history, GDPR-erasable.

Status: released on PyPI (pip install memgres) and GHCR — see the releases page for the current version. Core library, search (pgvector/Qdrant), multi-tenant identity (users / namespaces / scoped tokens), HTTP API and MCP server, all tested in CI against live Postgres + Qdrant.

memgres is a lightweight, drop-in memory layer — a Python library plus an optional HTTP/MCP service — backed by a single PostgreSQL database. You store documents (bodies of text an agent owns and edits), not facts an LLM guessed at. Every change is an authored diff with provenance, kept in a tamper-evident history that you can still delete when the law says you must.

Why memgres exists

memgres is a document store where you own the write path — not a fact store that lets a model decide what to remember for you.

• You write the whole body or a unified diff — nothing re-interprets your text on the way in.
• Concurrency is guarded by content hash (optimistic locking): you send the hash of the body you edited; the write applies only if the current body still matches, otherwise you get a 409 and re-read. No lost updates, no silent overwrites.
• Every change is stored as a hash-chained unified diff with source/reason provenance — git-like history you can replay and attribute line by line.
• History rows are deletable: real GDPR erasure, not "hidden from results but still on disk".

Reach for memgres when you want auditable, authored, versioned text memory.

Advantages

Design at a glance

memgres (core library, no HTTP dependency)
  ├─ store        write (whole body OR unified diff) · get · recall · move · forget
  ├─ diffing      unified diff make/apply + content hash (optimistic locking)
  ├─ blame        line-attributed document + reconstruct any past version
  ├─ organize     tags (text[] + GIN) · tree (ltree path + GiST, fast subtree select)
  ├─ search       lexical (Postgres FTS)  +  semantic (pgvector or Qdrant)  +  hybrid
  ├─ embeddings   provider via env: none | local (sentence-transformers) | cloud (Jina/OpenAI)
  └─ config       every limit via env (body/write size, TTL, key mode, …)

optional layers on top of the same core:
  ├─ HTTP API (FastAPI)   REST + OpenAPI
  └─ MCP server           write/recall/get/blame/move/forget as MCP tools

Record model: one memory = one mutable body (up to a configurable ceiling, default 256 KB) plus metadata — tags (cross-cutting labels, text[] + GIN), a path (its place in an ltree tree), timestamps, and per-diff provenance (source/reason, kept in history). A single write/diff is capped smaller (default 16 KB), so large bodies accrue over many authored diffs. Organization is two orthogonal axes: the tree is where a memory lives (one place, subtree-selectable); tags are what it's about (many, overlapping). Both filter either search — narrow a semantic query to a subtree, or list a tag across the tree.

Isolation: optional multi-tenant identity keeps tenants from seeing each other's memories — users own namespaces, and rotatable, permission-scoped tokens authenticate as a user (turned on with MEMGRES_KEY_MODE=open|managed; see docs/TENANCY.md). Encryption at rest is left to the deployment — Postgres/managed-PG/disk TDE stays transparent to queries, so search keeps working; memgres deliberately does not encrypt bodies application-side (that would make them unsearchable, which is why no comparable tool does it either). GDPR erasure is real: forget() hard-deletes the row, its vectors, and crypto-shreds the history chain. All limits are env-configurable, so the same code serves a single-user embed and a capped multi-tenant service.

Quickstart

Run everything with Docker — pgvector, the memgres service (HTTP on :8080) and an MCP server (Streamable HTTP on :8765), schema auto-migrated on startup. Just grab the compose file (it pulls the published image, so there's nothing to build):

curl -O https://raw.githubusercontent.com/mozgsml/memgres/main/docker-compose.yml
docker compose up

Defaults suit a single-user setup with no auth. To change limits, the embedding provider, tokens, … drop a .env beside it — every MEMGRES_* is optional (see Configuration or .env.example).

Give it to an LLM / agent — no code (MCP). Point any URL-capable MCP client (Cursor, Cline, Claude Desktop, …) at the running server; the model gets memory_write, memory_recall, memory_get, memory_list, memory_blame, memory_history, memory_move, memory_forget, memory_server_info as tools:

{
  "mcpServers": {
    "memgres": { "url": "http://localhost:8765/mcp" }
  }
}

Then just tell the model "remember X" / "what do you know about Y?" and it calls the tools — nothing else to run. (For stdio-only clients, semantic recall, and multi-tenant tokens, see Use it with an LLM / agent (MCP) and docs/TENANCY.md.)

Also a plain HTTP API — the same service on :8080 (GET /healthz → {"ok":true}), for when you drive the agent loop yourself:

# create a memory
curl -sX POST localhost:8080/memories \
  -H 'content-type: application/json' \
  -d '{"body":"Postgres tuning notes\nshared_buffers = 25% RAM\n","tags":["db"],"path":"ops.postgres","source":"me"}'
# → {"id":"…","content_hash":"…","seq":1, …}

# recall (lexical out of the box; semantic once you set an embedding provider)
curl -s 'localhost:8080/recall?q=postgres%20tuning'

# edit by unified diff, guarded by the hash you edited (409 if stale)
curl -sX PATCH localhost:8080/memories/$ID \
  -H 'content-type: application/json' \
  -d '{"diff":"--- \n+++ \n@@ -2 +2 @@\n-shared_buffers = 25% RAM\n+shared_buffers = 40% RAM\n","base_hash":"'$HASH'","source":"me","reason":"bump"}'

# who wrote each line (grouped into author-blocks by default)
curl -s localhost:8080/memories/$ID/blame

As a Python library (no HTTP)

pip install memgres              # core library
pip install "memgres[server]"    # + HTTP API
pip install "memgres[mcp]"       # + MCP server
# extras: local (sentence-transformers), qdrant (Qdrant backend)

from memgres import Store, load_config, migrate
import psycopg

cfg  = load_config()                       # reads MEMGRES_* env
conn = psycopg.connect(cfg.database_url)
migrate(conn, cfg)                         # idempotent; stamps embed model/dim

s = Store(cfg, conn=conn)
m = s.write(body="remember this\n", tags=["note"], path="misc.reminder", source="me")

# edit: whole body OR a diff carrying the base hash (optimistic concurrency)
m = s.write(id=m.id, body="remember this, updated\n", base_hash=m.content_hash, reason="tweak")

hits  = s.recall(None, "what did I remember?", k=5)          # lexical / semantic / hybrid / auto
blame = s.annotate_grouped(None, m.id)                        # [{start,end,source,reason,…}]
old   = s.reconstruct(None, m.id, 1)                          # body as of version 1
s.forget(None, m.id)                                          # hard-erase + history

Or pull the container image (public, no login):

docker pull ghcr.io/mozgsml/memgres:latest

Ways to run it

Not sure which fits? Start with the decision guide: docs/CHOOSING.md. In short — more than one user → run the Docker server (shared), not a per-machine install.

1. docker compose up — pgvector + service, nothing to configure. For a dedicated vector service instead, docker compose --profile qdrant up and set MEMGRES_VECTOR_BACKEND=qdrant (Qdrant ranks vectors; Postgres still holds bodies and does tag/subtree/TTL filtering).
2. Your own Postgres — install the [server] extra (above), point MEMGRES_DATABASE_URL at it, run memgres-server (migrates on startup).
3. Embedded library — install the core package, use Store directly, no HTTP at all.
4. Split service (many clients) — a stateless API tier that only flags writes plus a scalable memgres-worker tier that embeds; see docs/DEPLOYMENT.md and deploy/docker-compose.yml. Switch the embedding model later with memgres-reembed.

Semantic recall is optional: the default MEMGRES_EMBED_PROVIDER=none gives you lexical FTS with zero models. Turn on local (sentence-transformers), a cloud API (openai/jina), or any OpenAI-compatible server (LM Studio, Ollama, …) when you want meaning-based search — see docs/EMBEDDINGS.md for choosing local vs cloud and docs/BACKENDS.md for copy-paste setups. The model id + dimension get stamped into the schema and a later mismatch hard-fails instead of silently returning garbage.

Configuration

Everything is env, all optional (defaults suit a single-user embed). Full list in .env.example.

HTTP API

Every memory/recall route also takes optional space (one of your namespaces by name) and space_id (canonical id, for shared spaces). In open/managed mode the token goes in Authorization: Bearer <token> or X-Memgres-Token; there are also request-access and /admin/* provisioning routes — see docs/TENANCY.md. OpenAPI/Swagger is at /docs. Store errors map to status codes: 409 stale-hash conflict, 404 not found, 413 too large, 401/403 auth.

/healthz and /info are intentionally unauthenticated (and the MCP memory_server_info tool is always available): /info returns only effective configuration — limits, embedding provider/model/dimension, available recall modes, vector backend, key mode — and never a secret (no DB URL, token, API key, or admin token). It exists so a client can discover a deployment's capabilities before authenticating. If a managed deployment must not disclose even that metadata, put it behind your reverse proxy's auth.

Use it with an LLM / agent (MCP)

memgres itself never calls an LLM — it's the memory, not the model. Your LLM uses it one of two ways:

A. Via MCP — the model calls memgres tools directly (Cursor, Cline, Claude Desktop, any MCP client). Zero code.

docker compose up already starts an MCP server over Streamable HTTP at http://localhost:8765/mcp. Point a URL-capable MCP client at it — nothing else to run:

{
  "mcpServers": {
    "memgres": { "url": "http://localhost:8765/mcp" }
  }
}

For stdio-only clients, install the command and let the client spawn it:

pip install "memgres[mcp]"

{
  "mcpServers": {
    "memgres": {
      "command": "memgres-mcp",
      "env": {
        "MEMGRES_DATABASE_URL": "postgresql://memgres:memgres@localhost:5432/memgres",
        "MEMGRES_KEY_MODE": "open",
        "MEMGRES_TOKEN": "mgk_…"
      }
    }
  }
}

Either way the model gets tools memory_write, memory_recall, memory_get, memory_list, memory_blame, memory_history, memory_move, memory_forget, memory_server_info. Tell it "remember X" / "what do you know about Y?" and it calls them. (For semantic recall add the embedding env vars — see docs/BACKENDS.md.)

Isolation — pin the identity in the client config

The agent never handles the token (so the model spends nothing echoing a secret and can't switch user):

• stdio: set MEMGRES_KEY_MODE=open + MEMGRES_TOKEN=<mgk_…> in the client's env block (above).
• http: send the token as a header — one shared endpoint then serves many clients, each pinned to its own user:

  { "mcpServers": { "memgres": {
      "url": "http://localhost:8765/mcp",
      "headers": { "Authorization": "Bearer mgk_…" } } } }
  

A namespace-scoped token also locks the agent to one space. Only a genuinely multi-tenant endpoint (open/managed, no pinned token) exposes a token tool argument for the model to supply — force it either way with MEMGRES_MCP_TOKEN_ARG=on|off. Single mode needs no token. Full model in docs/TENANCY.md.

B. From your own agent code — your loop calls the HTTP API or the Store library after the model produces text (see the examples above). Use this when you control the agent loop and decide when to write/recall.

Multi-tenant, tokens & isolation

There is no token for single-user / local use — leave everything default (MEMGRES_KEY_MODE=single) and it just works. Two token concepts exist, unrelated:

• Embedding API key (MEMGRES_EMBED_API_KEY) — only if you use a cloud embedding provider (openai/jina) for semantic recall. Local models and lexical-only need none. This is the key from your embedding provider.

• Access token (multi-tenant, MEMGRES_KEY_MODE=open|managed) — a bearer credential of the form mgk_ + 43 url-safe chars, authenticating as a user. Tokens are rotatable, expirable, revocable, and restrictable (a permission ceiling + optional scope to one namespace); the secret is stored only as a hash. Rotating a token does not move you to a new empty space — many tokens can back one user, and namespaces are addressed by name or id.

  python -c "import secrets; print('mgk_'+secrets.token_urlsafe(32))"   # open mode: mint your own
  

  Sent as Authorization: Bearer <token> / X-Memgres-Token (HTTP + MCP over http), the token argument (library), or MEMGRES_TOKEN in env for a single-tenant endpoint. Over MCP the agent never passes it — you pin it in the client config (env or headers). It's a bearer secret with no recovery — treat it like a password.

Full model — users, namespaces, permissions, request-access, admin provisioning — in docs/TENANCY.md.

License

MIT — see LICENSE. Fully self-hostable, no gated features.