memgres 0.1.0__tar.gz → 0.2.0__tar.gz

{memgres-0.1.0 → memgres-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.1.0
+Version: 0.2.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT
@@ -28,6 +28,7 @@ Requires-Dist: uvicorn>=0.29; extra == "server"
 Requires-Dist: psycopg-pool>=3.2; extra == "server"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2; extra == "mcp"
+Requires-Dist: psycopg-pool>=3.2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Dynamic: license-file
@@ -39,7 +40,7 @@ Dynamic: license-file
 
 **Versioned document memory for AI agents — one Postgres, lexical *or* semantic recall, diff-based history, GDPR-erasable.**
 
-> Status: early. Core library, search, HTTP API and MCP server are implemented and tested against a live pgvector Postgres.
+> Status: v0.2.0 — on [PyPI](https://pypi.org/project/memgres/) (`pip install memgres`) and [GHCR](https://ghcr.io/mozgsml/memgres). 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.
 
@@ -71,7 +72,7 @@ Reach for memgres when you want **auditable, authored, versioned text memory**.
 | **Lexical *and* semantic (hybrid)** | Exact identifiers/codes go to lexical (where [dense retrieval alone stumbles](https://tianpan.co/blog/2026-04-12-hybrid-search-production-bm25-dense-embeddings)); meaning-based queries go to vectors; hybrid fuses both with RRF. |
 | **Embedding-model safety by construction** | The model id + dimension are stamped into the schema; a mismatch **hard-fails** instead of silently returning garbage. |
 | **TTL renewed on read** | Active memory persists because it's used; abandoned memory expires itself. Storage self-cleans instead of growing forever. |
-| **Optional token namespaces** | Multi-tenant isolation when you need it (secret token → namespace); nothing to configure for single-user. |
+| **Optional multi-tenant identity** | Users, namespaces and rotatable scoped tokens when you need isolation; nothing to configure for single-user. |
 | **Fast subtree recall via `ltree`** | Memories form a real tree; `path <@ 'a.b'` pulls a whole subtree in one GiST index scan, no recursive walk that degrades with depth. |
 | **Git-blame + version reconstruct** | Every line carries who last changed it (grouped into author-blocks); any past version reconstructs from history — no replaying diffs yourself. |
 | **One Postgres, one backup** | The whole thing is `pg_dump`-able; the vector index rebuilds from the source of truth. No second datastore to run or back up. |
@@ -89,7 +90,7 @@ memgres (core library, no HTTP dependency)
   ├─ 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, namespaces, …)
+  └─ config       every limit via env (body/write size, TTL, key mode, …)
 
 optional layers on top of the same core:
   ├─ HTTP API (FastAPI)   REST + OpenAPI
@@ -98,18 +99,35 @@ optional layers on top of the same core:
 
 **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 token *namespaces* keep tenants from seeing each other's memories (namespace = hash of a secret token, so one wallet can back many clients). 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.
+**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](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
 
-**The whole thing, one command** — brings up `pgvector` + the memgres service on `http://localhost:8080`, schema auto-migrated on startup:
+**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):
 
 ```bash
-docker compose up            # → http://localhost:8080  (GET /healthz → {"ok":true})
+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](#configuration) or [.env.example](.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_blame`, `memory_history`, `memory_move`, `memory_forget` as tools:
+
+```json
+{
+  "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)](#use-it-with-an-llm--agent-mcp) and [docs/TENANCY.md](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:
+
 ```bash
 # create a memory
 curl -sX POST localhost:8080/memories \
@@ -131,6 +149,13 @@ curl -s localhost:8080/memories/$ID/blame
 
 ### As a Python library (no HTTP)
 
+```bash
+pip install memgres              # core library
+pip install "memgres[server]"    # + HTTP API
+pip install "memgres[mcp]"       # + MCP server
+# extras: local (sentence-transformers), qdrant (Qdrant backend)
+```
+
 ```python
 from memgres import Store, load_config, migrate
 import psycopg
@@ -151,18 +176,7 @@ old   = s.reconstruct(None, m.id, 1)                          # body as of versi
 s.forget(None, m.id)                                          # hard-erase + history
 ```
 
-### Install
-
-> Not on PyPI yet — install from git (or clone and `pip install -e .`):
-
-```bash
-pip install "git+https://github.com/mozgsml/memgres"            # core library
-pip install "memgres[server] @ git+https://github.com/mozgsml/memgres"   # + HTTP API
-pip install "memgres[mcp]   @ git+https://github.com/mozgsml/memgres"    # + MCP server
-# extras: local (sentence-transformers), qdrant (Qdrant backend)
-```
-
-Or pull the container image:
+Or pull the container image (public, no login):
 
 ```bash
 docker pull ghcr.io/mozgsml/memgres:latest
@@ -183,11 +197,14 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | Variable | Default | Meaning |
 |---|---|---|
 | `MEMGRES_DATABASE_URL` | libpq env | Postgres connection string |
+| `MEMGRES_POOL_SIZE` | `4` | max pooled DB connections (HTTP + http-MCP servers); raise for many concurrent clients, `1` to serialize |
 | `MEMGRES_MAX_BODY_BYTES` | `262144` | ceiling for a whole record body (256 KB) |
 | `MEMGRES_MAX_WRITE_BYTES` | `16384` | ceiling for one write/diff payload (≤ body) |
 | `MEMGRES_RETENTION_DAYS` | `0` | `0` = keep forever; `>0` = expire N days after last touch |
 | `MEMGRES_RENEW_ON_READ` | `true` | a read pushes the expiry clock forward |
-| `MEMGRES_NAMESPACES` | `false` | `true` = each caller sends a secret token; namespace = its hash |
+| `MEMGRES_KEY_MODE` | `single` | `single` (no auth, one space) · `open` (bring-your-own token, self-registers) · `managed` (admin-provisioned). See [docs/TENANCY.md](docs/TENANCY.md) |
+| `MEMGRES_ADMIN_TOKEN` | — | global admin bearer for provisioning (managed mode) |
+| `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |
 | `MEMGRES_HISTORY` | `true` | keep the hash-chained diff history (deleted with the record) |
@@ -209,20 +226,112 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `GET` | `/memories/{id}/blame` | line attribution; `?group`, `?text`, `?lines=1,3-5` |
 | `GET` | `/memories/{id}/at/{seq}` | body reconstructed at a version |
 | `GET` | `/recall` | `?q=&k=&mode=&tags=&path_prefix=` |
+| `GET` | `/spaces` | namespaces this token can reach (identity modes) |
 | `GET` | `/healthz` | liveness |
 
-Namespace token (when `MEMGRES_NAMESPACES=true`) goes in `Authorization: Bearer <token>` or `X-Memgres-Token`. OpenAPI/Swagger is served at `/docs`. Store errors map to status codes: `409` stale-hash conflict, `404` not found, `413` too large, `401` missing token.
+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](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.
+
+## Use it with an LLM / agent (MCP)
 
-## MCP server
+memgres itself **never calls an LLM** — it's the memory, not the model. Your LLM
+uses it one of two ways:
 
-The same store is exposed to MCP clients (Claude Desktop, etc.) over stdio:
+**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:
+
+```json
+{
+  "mcpServers": {
+    "memgres": { "url": "http://localhost:8765/mcp" }
+  }
+}
+```
+
+For **stdio-only** clients, install the command and let the client spawn it:
 
 ```bash
-pip install "memgres[mcp] @ git+https://github.com/mozgsml/memgres"
-memgres-mcp                    # needs MEMGRES_DATABASE_URL; migrates on startup
+pip install "memgres[mcp]"
+```
+```json
+{
+  "mcpServers": {
+    "memgres": {
+      "command": "memgres-mcp",
+      "env": {
+        "MEMGRES_DATABASE_URL": "postgresql://memgres:memgres@localhost:5432/memgres",
+        "MEMGRES_KEY_MODE": "open",
+        "MEMGRES_TOKEN": "mgk_…"
+      }
+    }
+  }
+}
 ```
 
-Tools: `memory_write` (create or edit by body/diff), `memory_get`, `memory_recall`, `memory_blame`, `memory_history`, `memory_move`, `memory_forget`. Point your MCP client's config at the `memgres-mcp` command.
+Either way the model gets tools `memory_write`, `memory_recall`, `memory_get`,
+`memory_blame`, `memory_history`, `memory_move`, `memory_forget`. 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](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:
+  ```json
+  { "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](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.
+
+## Tokens & auth
+
+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.
+
+  ```bash
+  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](docs/TENANCY.md)**.
 
 ---
 

{memgres-0.1.0 → memgres-0.2.0}/README.md

@@ -5,7 +5,7 @@
 
 **Versioned document memory for AI agents — one Postgres, lexical *or* semantic recall, diff-based history, GDPR-erasable.**
 
-> Status: early. Core library, search, HTTP API and MCP server are implemented and tested against a live pgvector Postgres.
+> Status: v0.2.0 — on [PyPI](https://pypi.org/project/memgres/) (`pip install memgres`) and [GHCR](https://ghcr.io/mozgsml/memgres). 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.
 
@@ -37,7 +37,7 @@ Reach for memgres when you want **auditable, authored, versioned text memory**.
 | **Lexical *and* semantic (hybrid)** | Exact identifiers/codes go to lexical (where [dense retrieval alone stumbles](https://tianpan.co/blog/2026-04-12-hybrid-search-production-bm25-dense-embeddings)); meaning-based queries go to vectors; hybrid fuses both with RRF. |
 | **Embedding-model safety by construction** | The model id + dimension are stamped into the schema; a mismatch **hard-fails** instead of silently returning garbage. |
 | **TTL renewed on read** | Active memory persists because it's used; abandoned memory expires itself. Storage self-cleans instead of growing forever. |
-| **Optional token namespaces** | Multi-tenant isolation when you need it (secret token → namespace); nothing to configure for single-user. |
+| **Optional multi-tenant identity** | Users, namespaces and rotatable scoped tokens when you need isolation; nothing to configure for single-user. |
 | **Fast subtree recall via `ltree`** | Memories form a real tree; `path <@ 'a.b'` pulls a whole subtree in one GiST index scan, no recursive walk that degrades with depth. |
 | **Git-blame + version reconstruct** | Every line carries who last changed it (grouped into author-blocks); any past version reconstructs from history — no replaying diffs yourself. |
 | **One Postgres, one backup** | The whole thing is `pg_dump`-able; the vector index rebuilds from the source of truth. No second datastore to run or back up. |
@@ -55,7 +55,7 @@ memgres (core library, no HTTP dependency)
   ├─ 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, namespaces, …)
+  └─ config       every limit via env (body/write size, TTL, key mode, …)
 
 optional layers on top of the same core:
   ├─ HTTP API (FastAPI)   REST + OpenAPI
@@ -64,18 +64,35 @@ optional layers on top of the same core:
 
 **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 token *namespaces* keep tenants from seeing each other's memories (namespace = hash of a secret token, so one wallet can back many clients). 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.
+**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](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
 
-**The whole thing, one command** — brings up `pgvector` + the memgres service on `http://localhost:8080`, schema auto-migrated on startup:
+**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):
 
 ```bash
-docker compose up            # → http://localhost:8080  (GET /healthz → {"ok":true})
+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](#configuration) or [.env.example](.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_blame`, `memory_history`, `memory_move`, `memory_forget` as tools:
+
+```json
+{
+  "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)](#use-it-with-an-llm--agent-mcp) and [docs/TENANCY.md](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:
+
 ```bash
 # create a memory
 curl -sX POST localhost:8080/memories \
@@ -97,6 +114,13 @@ curl -s localhost:8080/memories/$ID/blame
 
 ### As a Python library (no HTTP)
 
+```bash
+pip install memgres              # core library
+pip install "memgres[server]"    # + HTTP API
+pip install "memgres[mcp]"       # + MCP server
+# extras: local (sentence-transformers), qdrant (Qdrant backend)
+```
+
 ```python
 from memgres import Store, load_config, migrate
 import psycopg
@@ -117,18 +141,7 @@ old   = s.reconstruct(None, m.id, 1)                          # body as of versi
 s.forget(None, m.id)                                          # hard-erase + history
 ```
 
-### Install
-
-> Not on PyPI yet — install from git (or clone and `pip install -e .`):
-
-```bash
-pip install "git+https://github.com/mozgsml/memgres"            # core library
-pip install "memgres[server] @ git+https://github.com/mozgsml/memgres"   # + HTTP API
-pip install "memgres[mcp]   @ git+https://github.com/mozgsml/memgres"    # + MCP server
-# extras: local (sentence-transformers), qdrant (Qdrant backend)
-```
-
-Or pull the container image:
+Or pull the container image (public, no login):
 
 ```bash
 docker pull ghcr.io/mozgsml/memgres:latest
@@ -149,11 +162,14 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | Variable | Default | Meaning |
 |---|---|---|
 | `MEMGRES_DATABASE_URL` | libpq env | Postgres connection string |
+| `MEMGRES_POOL_SIZE` | `4` | max pooled DB connections (HTTP + http-MCP servers); raise for many concurrent clients, `1` to serialize |
 | `MEMGRES_MAX_BODY_BYTES` | `262144` | ceiling for a whole record body (256 KB) |
 | `MEMGRES_MAX_WRITE_BYTES` | `16384` | ceiling for one write/diff payload (≤ body) |
 | `MEMGRES_RETENTION_DAYS` | `0` | `0` = keep forever; `>0` = expire N days after last touch |
 | `MEMGRES_RENEW_ON_READ` | `true` | a read pushes the expiry clock forward |
-| `MEMGRES_NAMESPACES` | `false` | `true` = each caller sends a secret token; namespace = its hash |
+| `MEMGRES_KEY_MODE` | `single` | `single` (no auth, one space) · `open` (bring-your-own token, self-registers) · `managed` (admin-provisioned). See [docs/TENANCY.md](docs/TENANCY.md) |
+| `MEMGRES_ADMIN_TOKEN` | — | global admin bearer for provisioning (managed mode) |
+| `MEMGRES_TOKEN` | — | default token used when a call passes none (single-tenant endpoints) |
 | `MEMGRES_TREE` | `true` | `ltree` path column + GiST index (fast subtree select) |
 | `MEMGRES_REQUIRE_PARENT` | `false` | `true` = a node's parent path must already exist |
 | `MEMGRES_HISTORY` | `true` | keep the hash-chained diff history (deleted with the record) |
@@ -175,20 +191,112 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `GET` | `/memories/{id}/blame` | line attribution; `?group`, `?text`, `?lines=1,3-5` |
 | `GET` | `/memories/{id}/at/{seq}` | body reconstructed at a version |
 | `GET` | `/recall` | `?q=&k=&mode=&tags=&path_prefix=` |
+| `GET` | `/spaces` | namespaces this token can reach (identity modes) |
 | `GET` | `/healthz` | liveness |
 
-Namespace token (when `MEMGRES_NAMESPACES=true`) goes in `Authorization: Bearer <token>` or `X-Memgres-Token`. OpenAPI/Swagger is served at `/docs`. Store errors map to status codes: `409` stale-hash conflict, `404` not found, `413` too large, `401` missing token.
+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](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.
+
+## Use it with an LLM / agent (MCP)
 
-## MCP server
+memgres itself **never calls an LLM** — it's the memory, not the model. Your LLM
+uses it one of two ways:
 
-The same store is exposed to MCP clients (Claude Desktop, etc.) over stdio:
+**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:
+
+```json
+{
+  "mcpServers": {
+    "memgres": { "url": "http://localhost:8765/mcp" }
+  }
+}
+```
+
+For **stdio-only** clients, install the command and let the client spawn it:
 
 ```bash
-pip install "memgres[mcp] @ git+https://github.com/mozgsml/memgres"
-memgres-mcp                    # needs MEMGRES_DATABASE_URL; migrates on startup
+pip install "memgres[mcp]"
+```
+```json
+{
+  "mcpServers": {
+    "memgres": {
+      "command": "memgres-mcp",
+      "env": {
+        "MEMGRES_DATABASE_URL": "postgresql://memgres:memgres@localhost:5432/memgres",
+        "MEMGRES_KEY_MODE": "open",
+        "MEMGRES_TOKEN": "mgk_…"
+      }
+    }
+  }
+}
 ```
 
-Tools: `memory_write` (create or edit by body/diff), `memory_get`, `memory_recall`, `memory_blame`, `memory_history`, `memory_move`, `memory_forget`. Point your MCP client's config at the `memgres-mcp` command.
+Either way the model gets tools `memory_write`, `memory_recall`, `memory_get`,
+`memory_blame`, `memory_history`, `memory_move`, `memory_forget`. 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](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:
+  ```json
+  { "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](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.
+
+## Tokens & auth
+
+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.
+
+  ```bash
+  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](docs/TENANCY.md)**.
 
 ---
 

{memgres-0.1.0 → memgres-0.2.0}/memgres/__init__.py

@@ -22,6 +22,13 @@ from .schema import migrate, SchemaMismatch, SCHEMA_VERSION
 from .search import Hit, recall
 from .blame import annotate, annotate_grouped, reconstruct, replay
 from .store import Store, Memory, Conflict, NotFound, TooLarge, NoParent
+from .identity import (
+    Principal, AuthError, SpaceNotFound,
+    resolve, resolve_space, new_token, valid_format,
+    create_user, create_namespace, list_spaces,
+    issue_token, register_token, revoke_token, list_tokens,
+    request_access, approve_request, deny_request, list_requests,
+)
 
 __all__ = [
     "Config", "load_config",
@@ -31,4 +38,9 @@ __all__ = [
     "migrate", "SchemaMismatch", "SCHEMA_VERSION",
     "Hit", "recall",
     "annotate", "annotate_grouped", "reconstruct", "replay",
+    "Principal", "AuthError", "SpaceNotFound",
+    "resolve", "resolve_space", "new_token", "valid_format",
+    "create_user", "create_namespace", "list_spaces",
+    "issue_token", "register_token", "revoke_token", "list_tokens",
+    "request_access", "approve_request", "deny_request", "list_requests",
 ]

{memgres-0.1.0 → memgres-0.2.0}/memgres/config.py

@@ -49,7 +49,11 @@ class Config:
     retention_days: int          # 0 = forever; >0 = expire N days after last touch
     renew_on_read: bool          # a read pushes the expiry clock forward
     # multi-tenant isolation
-    namespaces_enabled: bool     # False = single space; True = secret-token namespaces
+    token: str                   # default token used when a call passes none
+                                 # (set in MCP/env for a single-tenant deployment)
+    # identity / tenancy (see docs/TENANCY.md)
+    key_mode: str                # single | open | managed  (how tokens/users are minted)
+    admin_token: str             # global-admin bearer: provision users/namespaces anywhere
     # organization
     tree_enabled: bool           # ltree path column + GiST index for fast subtree selection
     require_parent: bool         # False = sparse paths (create food.apple with no food row);
@@ -67,8 +71,11 @@ class Config:
     embed_api_base: str
     # database
     database_url: str
+    pool_size: int               # max pooled connections (HTTP + http-MCP servers)
 
     def validate(self) -> None:
+        if self.pool_size < 1:
+            raise ValueError("MEMGRES_POOL_SIZE must be >= 1")
         if self.max_write_bytes > self.max_body_bytes:
             raise ValueError(
                 "MEMGRES_MAX_WRITE_BYTES must be <= MEMGRES_MAX_BODY_BYTES"
@@ -79,6 +86,8 @@ class Config:
             raise ValueError(f"unknown MEMGRES_EMBED_PROVIDER: {self.embed_provider}")
         if self.vector_backend not in ("pgvector", "qdrant"):
             raise ValueError(f"unknown MEMGRES_VECTOR_BACKEND: {self.vector_backend}")
+        if self.key_mode not in ("single", "open", "managed"):
+            raise ValueError(f"unknown MEMGRES_KEY_MODE: {self.key_mode}")
         if self.embed_provider != "none" and self.vector_backend == "pgvector" \
                 and self.embed_dim <= 0:
             raise ValueError(
@@ -94,7 +103,9 @@ def load() -> Config:
         max_write_bytes=_int("MEMGRES_MAX_WRITE_BYTES", 16_384),      # 16 KB
         retention_days=_int("MEMGRES_RETENTION_DAYS", 0),
         renew_on_read=_bool("MEMGRES_RENEW_ON_READ", True),
-        namespaces_enabled=_bool("MEMGRES_NAMESPACES", False),
+        token=_str("MEMGRES_TOKEN", ""),
+        key_mode=_str("MEMGRES_KEY_MODE", "single"),
+        admin_token=_str("MEMGRES_ADMIN_TOKEN", ""),
         tree_enabled=_bool("MEMGRES_TREE", True),
         require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),
         history_enabled=_bool("MEMGRES_HISTORY", True),
@@ -106,6 +117,7 @@ def load() -> Config:
         embed_api_key=_str("MEMGRES_EMBED_API_KEY", ""),
         embed_api_base=_str("MEMGRES_EMBED_API_BASE", ""),
         database_url=_str("MEMGRES_DATABASE_URL", ""),
+        pool_size=_int("MEMGRES_POOL_SIZE", 4),
     )
     cfg.validate()
     return cfg