memgres 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgres
-Version: 0.2.0
+Version: 0.3.0
 Summary: Drop-in memory for AI agents: one Postgres, lexical + semantic recall, diff-versioned history, GDPR-erasable.
 Author: mozgsml
 License-Expression: MIT
@@ -18,6 +18,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pysbd>=0.3
 Provides-Extra: local
 Requires-Dist: sentence-transformers>=3.0; extra == "local"
 Provides-Extra: qdrant
@@ -70,11 +71,12 @@ Reach for memgres when you want **auditable, authored, versioned text memory**.
 | **Hash-chained, GDPR-deletable history** | Tamper-evident provenance you can *still* erase: `forget()` hard-deletes the row, its vectors, and crypto-shreds the chain — no ["ghost vectors" left reconstructible in the index](https://arxiv.org/pdf/2606.18497). |
 | **Lexical works with zero embeddings** | Deploy with no model, no API, no GPU — Postgres full-text search out of the box. Turn on semantic recall only when you want it. |
 | **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. |
+| **Snippets, not walls of text** | Recall returns the most relevant slice of each hit plus its line number — semantic hits pick their best segment (embedded once, then cached), lexical uses `ts_headline`. Pass `full_body=false` for just the snippet. |
 | **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 TTL, renewed on read** | Off by default — memory is kept forever. Turn on a retention window and active memory persists because it's used, while abandoned memory expires itself: storage self-cleans instead of growing. |
 | **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. |
+| **Git-like 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. |
 | **Drop-in module, not a framework** | `pip install`, or `docker compose up`, or point at your own Postgres. No platform to adopt. |
 
@@ -114,7 +116,7 @@ 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:
+**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:
 
 ```json
 {
@@ -188,7 +190,7 @@ docker pull ghcr.io/mozgsml/memgres:latest
 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.
 
-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/BACKENDS.md](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.
+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](docs/EMBEDDINGS.md) for choosing local vs cloud and [docs/BACKENDS.md](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
 
@@ -200,7 +202,8 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `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_MAX_SOURCE_BYTES` / `_MAX_REASON_BYTES` | `2048` / `1024` | ceilings for a write's `source` / `reason` provenance |
+| `MEMGRES_RETENTION_DAYS` | `0` | `0` = keep forever (TTL off); `>0` = expire N days after last touch |
 | `MEMGRES_RENEW_ON_READ` | `true` | a read pushes the expiry clock forward |
 | `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) |
@@ -209,9 +212,13 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `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) |
 | `MEMGRES_FTS_LANGUAGE` | `simple` | Postgres FTS dictionary (`simple`/`english`/…) |
+| `MEMGRES_LEXICAL_MATCH` | `any` | lexical query words OR-ed (`any`) or AND-ed (`all`); per-call `match` overrides |
+| `MEMGRES_SNIPPET` | `true` | attach a best-match snippet + line to each hit (`MEMGRES_SNIPPET_*` tune size/semantic; `full_body` per call) |
+| `MEMGRES_LIST_PREVIEW_CHARS` | `120` | first-line preview length returned by `memory_list` |
 | `MEMGRES_VECTOR_BACKEND` | `pgvector` | `pgvector` (same DB) or `qdrant` (set `QDRANT_URL`, `QDRANT_API_KEY`, `MEMGRES_QDRANT_COLLECTION`) |
 | `MEMGRES_EMBED_PROVIDER` | `none` | `none` / `local` / `openai` / `jina` / `openai-compatible` (LM Studio, Ollama, vLLM, TEI…) |
 | `MEMGRES_EMBED_MODEL` / `_DIM` / `_API_KEY` / `_API_BASE` | — | model id · dimension (HTTP providers require it, `local` infers) · token · server URL |
+| `MEMGRES_EMBED_MAX_SEQ` | `0` | override the local model's max input length in tokens (`0` = the model's default) |
 
 ## HTTP API
 
@@ -225,8 +232,10 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `GET` | `/memories/{id}/history` | raw change chain |
 | `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` | `/recall` | `?q=&k=&mode=&tags=&path_prefix=&match=&snippet=&full_body=` |
+| `GET` | `/memories` | list a subtree, no query: `?path_prefix=&tags=&limit=&offset=` |
 | `GET` | `/spaces` | namespaces this token can reach (identity modes) |
+| `GET` | `/info` | effective config: limits, embed provider/model/dim, recall modes, backend |
 | `GET` | `/healthz` | liveness |
 
 Every memory/recall route also takes optional `space` (one of your namespaces by
@@ -237,6 +246,14 @@ also request-access and `/admin/*` provisioning routes — see
 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
@@ -278,12 +295,15 @@ pip install "memgres[mcp]"
 ```
 
 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).)
+`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](docs/BACKENDS.md).)
+
+### Isolation — pin the identity in the client config
 
-**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):
+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).
@@ -305,7 +325,7 @@ argument for the model to supply — force it either way with
 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
+## 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:

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

@@ -35,11 +35,12 @@ Reach for memgres when you want **auditable, authored, versioned text memory**.
 | **Hash-chained, GDPR-deletable history** | Tamper-evident provenance you can *still* erase: `forget()` hard-deletes the row, its vectors, and crypto-shreds the chain — no ["ghost vectors" left reconstructible in the index](https://arxiv.org/pdf/2606.18497). |
 | **Lexical works with zero embeddings** | Deploy with no model, no API, no GPU — Postgres full-text search out of the box. Turn on semantic recall only when you want it. |
 | **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. |
+| **Snippets, not walls of text** | Recall returns the most relevant slice of each hit plus its line number — semantic hits pick their best segment (embedded once, then cached), lexical uses `ts_headline`. Pass `full_body=false` for just the snippet. |
 | **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 TTL, renewed on read** | Off by default — memory is kept forever. Turn on a retention window and active memory persists because it's used, while abandoned memory expires itself: storage self-cleans instead of growing. |
 | **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. |
+| **Git-like 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. |
 | **Drop-in module, not a framework** | `pip install`, or `docker compose up`, or point at your own Postgres. No platform to adopt. |
 
@@ -79,7 +80,7 @@ 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:
+**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:
 
 ```json
 {
@@ -153,7 +154,7 @@ docker pull ghcr.io/mozgsml/memgres:latest
 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.
 
-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/BACKENDS.md](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.
+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](docs/EMBEDDINGS.md) for choosing local vs cloud and [docs/BACKENDS.md](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
 
@@ -165,7 +166,8 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `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_MAX_SOURCE_BYTES` / `_MAX_REASON_BYTES` | `2048` / `1024` | ceilings for a write's `source` / `reason` provenance |
+| `MEMGRES_RETENTION_DAYS` | `0` | `0` = keep forever (TTL off); `>0` = expire N days after last touch |
 | `MEMGRES_RENEW_ON_READ` | `true` | a read pushes the expiry clock forward |
 | `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) |
@@ -174,9 +176,13 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `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) |
 | `MEMGRES_FTS_LANGUAGE` | `simple` | Postgres FTS dictionary (`simple`/`english`/…) |
+| `MEMGRES_LEXICAL_MATCH` | `any` | lexical query words OR-ed (`any`) or AND-ed (`all`); per-call `match` overrides |
+| `MEMGRES_SNIPPET` | `true` | attach a best-match snippet + line to each hit (`MEMGRES_SNIPPET_*` tune size/semantic; `full_body` per call) |
+| `MEMGRES_LIST_PREVIEW_CHARS` | `120` | first-line preview length returned by `memory_list` |
 | `MEMGRES_VECTOR_BACKEND` | `pgvector` | `pgvector` (same DB) or `qdrant` (set `QDRANT_URL`, `QDRANT_API_KEY`, `MEMGRES_QDRANT_COLLECTION`) |
 | `MEMGRES_EMBED_PROVIDER` | `none` | `none` / `local` / `openai` / `jina` / `openai-compatible` (LM Studio, Ollama, vLLM, TEI…) |
 | `MEMGRES_EMBED_MODEL` / `_DIM` / `_API_KEY` / `_API_BASE` | — | model id · dimension (HTTP providers require it, `local` infers) · token · server URL |
+| `MEMGRES_EMBED_MAX_SEQ` | `0` | override the local model's max input length in tokens (`0` = the model's default) |
 
 ## HTTP API
 
@@ -190,8 +196,10 @@ Everything is env, all optional (defaults suit a single-user embed). Full list i
 | `GET` | `/memories/{id}/history` | raw change chain |
 | `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` | `/recall` | `?q=&k=&mode=&tags=&path_prefix=&match=&snippet=&full_body=` |
+| `GET` | `/memories` | list a subtree, no query: `?path_prefix=&tags=&limit=&offset=` |
 | `GET` | `/spaces` | namespaces this token can reach (identity modes) |
+| `GET` | `/info` | effective config: limits, embed provider/model/dim, recall modes, backend |
 | `GET` | `/healthz` | liveness |
 
 Every memory/recall route also takes optional `space` (one of your namespaces by
@@ -202,6 +210,14 @@ also request-access and `/admin/*` provisioning routes — see
 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
@@ -243,12 +259,15 @@ pip install "memgres[mcp]"
 ```
 
 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).)
+`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](docs/BACKENDS.md).)
+
+### Isolation — pin the identity in the client config
 
-**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):
+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).
@@ -270,7 +289,7 @@ argument for the model to supply — force it either way with
 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
+## 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:

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

@@ -45,6 +45,8 @@ class Config:
     # storage limits (bytes)
     max_body_bytes: int          # whole-record ceiling; grows to this via diffs
     max_write_bytes: int         # one write/diff payload ceiling (<= max_body)
+    max_source_bytes: int        # provenance `source` field ceiling (per write)
+    max_reason_bytes: int        # provenance `reason` field ceiling (per write)
     # retention
     retention_days: int          # 0 = forever; >0 = expire N days after last touch
     renew_on_read: bool          # a read pushes the expiry clock forward
@@ -62,13 +64,26 @@ class Config:
     history_enabled: bool        # keep hash-chained diff history (deleted with record)
     # search
     fts_language: str            # Postgres FTS dict: simple | english | russian | …
+    lexical_match: str           # any (OR-any words, default) | all (AND-all words)
     vector_backend: str          # pgvector (default) | qdrant
+    # snippets (a relevant slice of each recall hit's body + its line number)
+    snippet: bool                # attach a snippet+line to each hit
+    full_body: bool              # also return the whole body (off = snippet only)
+    snippet_semantic: bool       # semantic/hybrid hits use the best-matching
+                                 # segment (needs the model); off = ts_headline,
+                                 # avoiding per-query model calls on a paid API
+    snippet_seg_chars: int       # segment size for the best-segment snippet cache
+    snippet_seg_overlap: int     # chars shared between consecutive segments
+    # listing / browse
+    list_preview_chars: int      # first-line preview length for memory_list (0 = none)
     # embeddings
     embed_provider: str          # none | local | jina | openai | openai-compatible
     embed_model: str
     embed_dim: int               # 0 = infer from provider
     embed_api_key: str
     embed_api_base: str
+    embed_max_seq: int           # 0 = leave the model's default; >0 overrides
+                                 # the local model's max sequence length (tokens)
     # database
     database_url: str
     pool_size: int               # max pooled connections (HTTP + http-MCP servers)
@@ -76,6 +91,18 @@ class Config:
     def validate(self) -> None:
         if self.pool_size < 1:
             raise ValueError("MEMGRES_POOL_SIZE must be >= 1")
+        if self.max_source_bytes < 1:
+            raise ValueError("MEMGRES_MAX_SOURCE_BYTES must be >= 1")
+        if self.max_reason_bytes < 1:
+            raise ValueError("MEMGRES_MAX_REASON_BYTES must be >= 1")
+        if self.embed_max_seq < 0:
+            raise ValueError("MEMGRES_EMBED_MAX_SEQ must be >= 0")
+        if self.list_preview_chars < 0:
+            raise ValueError("MEMGRES_LIST_PREVIEW_CHARS must be >= 0")
+        if self.snippet_seg_chars < 1:
+            raise ValueError("MEMGRES_SNIPPET_SEG_CHARS must be >= 1")
+        if self.snippet_seg_overlap < 0:
+            raise ValueError("MEMGRES_SNIPPET_SEG_OVERLAP must be >= 0")
         if self.max_write_bytes > self.max_body_bytes:
             raise ValueError(
                 "MEMGRES_MAX_WRITE_BYTES must be <= MEMGRES_MAX_BODY_BYTES"
@@ -84,6 +111,8 @@ class Config:
                 "none", "local", "jina", "openai",
                 "openai-compatible", "compatible", "custom"):
             raise ValueError(f"unknown MEMGRES_EMBED_PROVIDER: {self.embed_provider}")
+        if self.lexical_match not in ("any", "all"):
+            raise ValueError(f"unknown MEMGRES_LEXICAL_MATCH: {self.lexical_match}")
         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"):
@@ -101,6 +130,8 @@ def load() -> Config:
     cfg = Config(
         max_body_bytes=_int("MEMGRES_MAX_BODY_BYTES", 262_144),      # 256 KB
         max_write_bytes=_int("MEMGRES_MAX_WRITE_BYTES", 16_384),      # 16 KB
+        max_source_bytes=_int("MEMGRES_MAX_SOURCE_BYTES", 2_048),     # 2 KB
+        max_reason_bytes=_int("MEMGRES_MAX_REASON_BYTES", 1_024),     # 1 KB
         retention_days=_int("MEMGRES_RETENTION_DAYS", 0),
         renew_on_read=_bool("MEMGRES_RENEW_ON_READ", True),
         token=_str("MEMGRES_TOKEN", ""),
@@ -110,12 +141,20 @@ def load() -> Config:
         require_parent=_bool("MEMGRES_REQUIRE_PARENT", False),
         history_enabled=_bool("MEMGRES_HISTORY", True),
         fts_language=_str("MEMGRES_FTS_LANGUAGE", "simple"),
+        lexical_match=_str("MEMGRES_LEXICAL_MATCH", "any"),
         vector_backend=_str("MEMGRES_VECTOR_BACKEND", "pgvector"),
+        snippet=_bool("MEMGRES_SNIPPET", True),
+        full_body=_bool("MEMGRES_FULL_BODY", True),
+        snippet_semantic=_bool("MEMGRES_SNIPPET_SEMANTIC", True),
+        snippet_seg_chars=_int("MEMGRES_SNIPPET_SEG_CHARS", 400),
+        snippet_seg_overlap=_int("MEMGRES_SNIPPET_SEG_OVERLAP", 80),
+        list_preview_chars=_int("MEMGRES_LIST_PREVIEW_CHARS", 120),
         embed_provider=_str("MEMGRES_EMBED_PROVIDER", "none"),
         embed_model=_str("MEMGRES_EMBED_MODEL", ""),
         embed_dim=_int("MEMGRES_EMBED_DIM", 0),
         embed_api_key=_str("MEMGRES_EMBED_API_KEY", ""),
         embed_api_base=_str("MEMGRES_EMBED_API_BASE", ""),
+        embed_max_seq=_int("MEMGRES_EMBED_MAX_SEQ", 0),
         database_url=_str("MEMGRES_DATABASE_URL", ""),
         pool_size=_int("MEMGRES_POOL_SIZE", 4),
     )

{memgres-0.2.0 → memgres-0.3.0}/memgres/embeddings.py

@@ -42,12 +42,14 @@ class Embedder:
 
 # ─── local: sentence-transformers ────────────────────────────────────────────
 class _LocalEmbedder(Embedder):
-    def __init__(self, model_name: str, want_dim: int):
+    def __init__(self, model_name: str, want_dim: int, max_seq: int = 0):
         from sentence_transformers import SentenceTransformer  # lazy: heavy import
 
         if not model_name:
             raise ValueError("MEMGRES_EMBED_MODEL is required for the local provider")
         self._model = SentenceTransformer(model_name, device="cpu")
+        if max_seq > 0:  # override the model's context window (tokens)
+            self._model.max_seq_length = max_seq
         self.dim = self._model.get_sentence_embedding_dimension()
         if want_dim and want_dim != self.dim:
             raise ValueError(
@@ -122,7 +124,7 @@ def get_embedder(cfg: Config) -> Optional[Embedder]:
     if p == "none":
         return None
     if p == "local":
-        return _LocalEmbedder(cfg.embed_model, cfg.embed_dim)
+        return _LocalEmbedder(cfg.embed_model, cfg.embed_dim, cfg.embed_max_seq)
     if p == "jina":
         return _HttpEmbedder(
             cfg.embed_model, cfg.embed_dim, cfg.embed_api_key,

memgres-0.3.0/memgres/info.py

@@ -0,0 +1,39 @@
+"""Effective server configuration, exposed read-only for introspection.
+
+An agent shouldn't have to guess the write ceilings, which recall modes are
+available, or how memories are embedded. ``server_info`` distills the loaded
+``Config`` (plus the live embedder's dimension, if one is built) into a small,
+non-sensitive dict. It deliberately carries **no** secrets — no token, no api
+key, no database url — so it is safe to return unauthenticated.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .config import Config
+
+
+def server_info(cfg: Config, embed_dim: Optional[int] = None) -> dict:
+    """Effective limits + capabilities, from the loaded config (and the live
+    embedder's dimension when available). Never includes secrets."""
+    lexical_only = cfg.embed_provider == "none"
+    dim = embed_dim if embed_dim is not None else (cfg.embed_dim or None)
+    return {
+        "limits": {
+            "max_body_bytes": cfg.max_body_bytes,
+            "max_write_bytes": cfg.max_write_bytes,
+            "max_source_bytes": cfg.max_source_bytes,
+            "max_reason_bytes": cfg.max_reason_bytes,
+        },
+        "embed": {
+            "provider": cfg.embed_provider,
+            "model": cfg.embed_model or None,
+            "dim": dim,
+        },
+        "recall_modes": ["lexical"] if lexical_only
+        else ["lexical", "semantic", "hybrid", "auto"],
+        "vector_backend": cfg.vector_backend,
+        "key_mode": cfg.key_mode,
+        "fts_language": cfg.fts_language,
+    }

{memgres-0.2.0 → memgres-0.3.0}/memgres/mcp_server.py

@@ -25,7 +25,7 @@ either. (``single`` mode needs no token at all.)
 
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import List, Literal, Optional
 
 from mcp.server.fastmcp import Context
 
@@ -165,21 +165,63 @@ def build_server(cfg: Optional[Config] = None):
                                          space=space, space_id=space_id))
 
     @mcp.tool()
-    def memory_recall(query: str, k: int = 10, mode: str = "auto",
+    def memory_recall(query: str, k: int = 10,
+                      mode: Literal["lexical", "semantic", "hybrid", "auto"] = "auto",
+                      match: Optional[Literal["any", "all"]] = None,
                       tags: Optional[List[str]] = None,
                       path_prefix: Optional[str] = None,
+                      snippet: Optional[bool] = None,
+                      full_body: Optional[bool] = None,
                       space: Optional[str] = None, space_id: Optional[str] = None,
                       token: Optional[str] = None, ctx: Context = None) -> List[dict]:
-        """Search memories. `mode`: lexical | semantic | hybrid | auto. Optionally
-        scope to a tag set (`tags`) or a subtree (`path_prefix`, e.g. 'ops.postgres').
+        """Search memories. `mode`: lexical | semantic | hybrid | auto. `match`
+        governs lexical word combination — defaults to OR-any (any query word
+        matches, forgiving recall); set 'all' to require every word (narrow).
+        Optionally scope to a tag set (`tags`) or a subtree (`path_prefix`, e.g.
+        'ops.postgres'). Each hit carries a `snippet` (+`line`) by default —
+        semantic/hybrid use the best-matching segment, lexical uses ts_headline;
+        pass `full_body=false` to get just the snippet, `snippet=false` for none.
         `space`/`space_id` pick which namespace to search (default: yours)."""
         with pool.connection() as conn:
-            return [{"id": h.id, "body": h.body, "tags": h.tags, "path": h.path,
-                     "score": h.score}
-                    for h in _store(conn).recall(
-                        _token(ctx, token), query, k=k, tags=tags,
-                        path_prefix=path_prefix, mode=mode,
-                        space=space, space_id=space_id)]
+            out = []
+            for h in _store(conn).recall(
+                    _token(ctx, token), query, k=k, tags=tags,
+                    path_prefix=path_prefix, mode=mode, match=match,
+                    snippet=snippet, full_body=full_body,
+                    space=space, space_id=space_id):
+                d = {"id": h.id, "tags": h.tags, "path": h.path,
+                     "score": h.score, "snippet": h.snippet, "line": h.line}
+                if h.body is not None:
+                    d["body"] = h.body
+                out.append(d)
+            return out
+
+    @mcp.tool()
+    def memory_list(path_prefix: Optional[str] = None,
+                    tags: Optional[List[str]] = None, limit: int = 50,
+                    offset: int = 0, space: Optional[str] = None,
+                    space_id: Optional[str] = None,
+                    token: Optional[str] = None, ctx: Context = None) -> List[dict]:
+        """BROWSE (enumerate) a subtree — NOT a search. Lists memories under
+        `path_prefix` (e.g. survey all of 'decisions.*') ordered by path, with a
+        short first-line `preview` of each. No query, no ranking; use
+        `memory_recall` when you want relevance search. Optionally narrow by
+        `tags`; `limit`/`offset` paginate. `space`/`space_id` pick the namespace
+        (default: yours)."""
+        with pool.connection() as conn:
+            return _store(conn).list(
+                _token(ctx, token), path_prefix=path_prefix, tags=tags,
+                limit=limit, offset=offset, space=space, space_id=space_id)
+
+    @mcp.tool()
+    def memory_server_info(ctx: Context = None) -> dict:
+        """The server's effective limits and capabilities (write ceilings, embed
+        provider/model/dim, available recall modes, vector backend, key mode, FTS
+        language). Non-sensitive config only — no secrets. Read it once so you
+        aren't guessing the limits."""
+        from .info import server_info
+        dim = embedder.dim if embedder is not None else None
+        return server_info(cfg, embed_dim=dim)
 
     @mcp.tool()
     def memory_blame(id: str, grouped: bool = True,
@@ -299,6 +341,26 @@ def build_server(cfg: Optional[Config] = None):
             if isinstance(_req, list) and "token" in _req:
                 _req.remove("token")
 
+    # Best-effort: with no embedder configured there is no vector backend, so
+    # semantic/hybrid recall can't run — drop them from memory_recall's `mode`
+    # enum so the model isn't offered modes that will only ever error. Purely
+    # cosmetic (same defensive style as the token pruning above): recall()'s
+    # backstop still raises on semantic-without-backend, and `lexical`/`auto`
+    # (auto resolves to lexical here) stay. Missing keys simply no-op.
+    if cfg.embed_provider == "none":
+        for _t in getattr(getattr(mcp, "_tool_manager", None), "_tools", {}).values():
+            if getattr(_t, "name", None) != "memory_recall":
+                continue
+            _params = getattr(_t, "parameters", None)
+            if not isinstance(_params, dict):
+                continue
+            _mode = _params.get("properties", {}).get("mode")
+            if not isinstance(_mode, dict):
+                continue
+            _enum = _mode.get("enum")
+            if isinstance(_enum, list):
+                _mode["enum"] = [m for m in _enum if m not in ("semantic", "hybrid")]
+
     return mcp
 
 

{memgres-0.2.0 → memgres-0.3.0}/memgres/schema.py

@@ -17,7 +17,7 @@ from pathlib import Path
 
 from .config import Config
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 3
 
 # Dev layout: repo/migrations next to the package. When packaged, migrations are
 # shipped inside the package (see pyproject) and this still resolves.
@@ -88,6 +88,27 @@ def _apply_vector(cur, cfg: Config) -> None:
         "CREATE INDEX IF NOT EXISTS memory_embedding_hnsw ON memory "
         "USING hnsw (embedding vector_cosine_ops)"
     )
+    # Per-memory segment vectors: a durable cache the (future) snippet flow fills
+    # lazily, keyed by the memory's content_hash (`src_hash`) so a body edit — a
+    # new hash — invalidates the cache and `forget` cascades them away. Offsets,
+    # not text: the snippet is sliced from the live body. A memory has few
+    # segments, ranked by a plain scan, so no HNSW here.
+    cur.execute(
+        f"""CREATE TABLE IF NOT EXISTS memory_segment (
+                memory_id uuid NOT NULL REFERENCES memory(id) ON DELETE CASCADE,
+                seq       int  NOT NULL,
+                seg_start int  NOT NULL,
+                seg_end   int  NOT NULL,
+                embedding vector({cfg.embed_dim}) NOT NULL,
+                src_hash  text NOT NULL,
+                namespace text NOT NULL,
+                PRIMARY KEY (memory_id, seq)
+            )"""
+    )
+    cur.execute(
+        "CREATE INDEX IF NOT EXISTS memory_segment_mid "
+        "ON memory_segment (memory_id)"
+    )
 
 
 def _stamp(cur, cfg: Config) -> None: