dsh-memento 0.4.5 → 0.5.0

package/ARCHITECTURE.md

@@ -105,7 +105,7 @@ memory 工具(add)
     - 实测（Node 22 内置 SQLite，FTS5 可用）：trigram 分词器无法索引单字 CJK 字符——`'中文测试'` 中查 `'中文'` 零命中；unicode61 把 CJK 连续段当一个 token，仅前缀可查。本插件语料以中文记忆为主，子串语义必须对 CJK 成立，instr 是唯一正确的内置引擎。
     - query 大小写不敏感（lower() 折叠 ASCII；CJK 无大小写不受影响），与面板过滤、sessionQuery 文本检索语义一致；replace/remove/consolidate 定位同语义（`lib/match.mjs` 的 `findUniqueMatch` 统一折叠，store 层 lower(instr) 与之一致）。
     - 召回排序：query 命中页的条目 `recall_count` +1、`last_recalled` 落地（SCHEMA v3 列）；排序 `recall_count DESC, updated_at DESC`（高频即重要）。快照仍走 `listEntries` 创建序（冻结块稳定优先）。
-    - 未来真正的升级路径是 harness 出现 embedding seam 后的语义召回（Provider 角色天然兼容），不是 FTS5。
+    - 未来真正的升级路径是 harness 出现 embedding seam 后的语义召回（Provider 角色天然兼容），不是 FTS5——本仓库已按决策 16 落地检索/嵌入 seam 的最小接入。
 
 11. **第三维 agentKey（per-agent 作用域，SCHEMA v3）**。
     - 写方 session 的 `header.agentPreset` 经 `agentKeyOf` 规范化（缺失→'' 共享层）；条目与提案落 `agent_key`。
@@ -175,3 +175,25 @@ gate → 预算复审 → 落盘 → 审计的完整流水线、唯一子串定
   仓库 CI 以黄金参考全绿；第三方 Provider 拷贝目录即可跑同一套用例。协议文档：
   `docs/protocol-v1.md`（双语）、`docs/schemas/dsh-memory-protocol-v1.schema.json`、
   `docs/adapters-guide.md`（双语）、`docs/upstream-proposal.md`（双语，官方 seam 采纳论证与迁移路径）。
+
+## P0：检索与嵌入 seam（可插拔检索 + 伪嵌入向量召回）
+
+### 16. 检索 Provider seam（lib/retrieval.mjs）与嵌入 Provider seam（lib/embedding.mjs）
+
+把 memory recall 的"检索"抽成可插拔检索器，并新增嵌入 Provider 接口，两者都是完整的
+三角色 seam（Service Definition / Provider / Consumer），零 DSH 依赖、零重依赖：
+
+- **检索 seam**（`ctx.memoryRetrieval`，`lib/retrieval.mjs`）：`RetrievalProvider` 契约 +
+  `RetrievalProviderRegistry`（register 可逆 / list / get / resolve）。内置 `SubstringRetriever`
+  是零依赖主路径（大小写不敏感子串 + 召回频次排序，语义与 `store.queryEntries` 的 instr 一致）；
+  `VectorRetriever` 是可选后端，消费嵌入 provider 做内存内暴力余弦排序（小语料，与决策 10 一致）。
+- **嵌入 seam**（`ctx.memoryEmbedding`，`lib/embedding.mjs`）：`EmbeddingProvider` 契约 +
+  `EmbeddingProviderRegistry`。默认 `FakeEmbeddingProvider` 是确定性的 token 哈希分桶计数 +
+  L2 归一化（固定 256 维单位向量）——它不做语义建模，只验证 seam 接线与余弦召回路径可复现；
+  真实嵌入由可选 provider 注册（本地模型 / peer），本仓库不引入 sqlite-vec / ONNX / 本地模型。
+- **Consumer 接线**：`Config.retrieval.vector`（默认 `false`）开启后，`memory_recall` 的记忆段改走
+  vector 检索器（可见集 = `visibleEntries` + 检索器排序 + `store.bumpRecall` + `recalled` 审计）；
+  默认仍走 `service.query` 的 substring 主路径，行为不变。
+- **探测 → 使用 → 优雅降级**：`detectVectorBackend` 只要求 embedding provider 可用；sqlite-vec 是
+  可选 loadable 扩展、恒不在本仓库打包（`sqliteVec: false`），P0 向量召回走内存内暴力余弦。
+  缺 embedding / vector 关闭时优雅降级回 substring，绝不响亮失败（可选后端缺失不是配置错误）。

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-08-26
+
+### Added
+
+- **Embedding Provider seam (`ctx.memoryEmbedding`)** — new `lib/embedding.mjs` registry ships a deterministic fake-hash provider by default, so third-party plugins can register real embedding backends behind the same Service Definition.
+- **Retrieval Provider seam (`ctx.memoryRetrieval`)** — new `lib/retrieval.mjs` registry keeps the built-in substring retriever as the zero-dependency main path and adds an optional `VectorRetriever` for semantic recall, enabled when `config.retrieval.vector` is `true` and an embedding provider is detected (graceful fallback to substring otherwise).
+- **stdio MCP server export** — new `bin/mcp-server.mjs` and `lib/mcp.mjs` expose the memory seam as an MCP server through the `dsh-memento-mcp` bin.
+
 ## [0.4.5] - 2026-08-23
 
 ### Changed

package/README.es.md

@@ -82,6 +82,7 @@ Todos los parámetros son campos Schemastery `Config` (modificables desde cordis
 | `recall.snippetCap` | `5` | Fragmentos por sesión en `memory_recall` |
 | `recall.snippetChars` | `300` | Caracteres de fragmento en `memory_recall` |
 | `recall.windowDays` | `30` | Ventana de antigüedad en días de `memory_recall` |
+| `retrieval.vector` | `false` | Interruptor de recuperación semántica: `true` activa la recuperación vectorial de `memory_recall` (incrustación hash falsa) cuando hay un proveedor de incrustación; en caso contrario degrada a subcadena |
 | `panelEntriesLimit` | `200` | Tamaño de página de entradas del panel web |
 | `panelAuditLimit` | `20` | Filas de auditoría del panel web por defecto |
 | `auditRetentionDays` | `0` | Retención de auditoría (0 = conservar para siempre) |
@@ -98,6 +99,44 @@ Todos los parámetros son campos Schemastery `Config` (modificables desde cordis
 | `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
 | web panel | client drawer | Solo lectura: explorar entradas, buscar, barras de presupuesto, cola de auditoría |
 
+## MCP server
+
+`dsh-memento` incluye un **servidor MCP** stdio de solo lectura (`dsh-memento-mcp`) para que clientes MCP externos (Claude, Codex, …) consulten el almacén de memoria sin el harness. Habla JSON-RPC 2.0 sobre JSON delimitado por saltos de línea (NDJSON): un objeto JSON por línea, sin tramado `Content-Length`.
+
+**Solo lectura.** La base de datos se abre con `readOnly: true` de `node:sqlite` (sin migraciones, sin escrituras WAL, sin incremento del contador de recuperación); si el archivo no existe, devuelve resultados vacíos en lugar de fallar.
+
+| Herramienta | Propósito |
+|---|---|
+| `memory_search` | `{query, limit?}` → entradas ordenadas (subcadena insensible a mayúsculas vía el seam del Provider de recuperación) |
+| `memory_stats` | `{}` → `{total, namespaces}` conteo de entradas + resumen por track/scope |
+
+Ejecución directa:
+
+```sh
+node bin/mcp-server.mjs
+# o, tras npm install: npx dsh-memento-mcp
+```
+
+La ruta de la base de datos es `$DSH_MEMENTO_DB_PATH` (absoluta, o relativa a `$DSH_HOME`); por defecto `$DSH_HOME/dsh-memento/memory.db`.
+
+Ejemplo para Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dsh-memento": {
+      "command": "npx",
+      "args": ["-y", "dsh-memento-mcp"],
+      "env": {
+        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
+      }
+    }
+  }
+}
+```
+
+El servidor es de solo lectura: sin red, sin escrituras, sin puerta de aprobación — solo búsqueda y estadísticas.
+
 ## How it's different
 
 | Plugin | Qué es | La diferencia de dsh-memento |

package/README.hi.md

@@ -82,6 +82,7 @@ dsh --profile web --dump-config | grep -A3 'id: memento'
 | `recall.snippetCap` | `5` | `memory_recall` में प्रति-सत्र स्निपेट |
 | `recall.snippetChars` | `300` | `memory_recall` स्निपेट अक्षर |
 | `recall.windowDays` | `30` | `memory_recall` की दिनों में हाल-समय विंडो |
+| `retrieval.vector` | `false` | सिमेंटिक रिकॉल स्विच: `true` से `memory_recall` वेक्टर रिकॉल (फ़ेक हैश एम्बेडिंग) सक्षम होता है जब कोई एम्बेडिंग प्रदाता उपलब्ध हो; अन्यथा सबस्ट्रिंग पर डिग्रेड होता है |
 | `panelEntriesLimit` | `200` | वेब पैनल प्रविष्टि पृष्ठ आकार |
 | `panelAuditLimit` | `20` | वेब पैनल डिफ़ॉल्ट ऑडिट पंक्तियाँ |
 | `auditRetentionDays` | `0` | ऑडिट अवधारण (0 = हमेशा रखें) |
@@ -98,6 +99,44 @@ dsh --profile web --dump-config | grep -A3 'id: memento'
 | `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
 | web panel | client drawer | केवल-पठन: प्रविष्टियाँ ब्राउज़ करें, खोजें, बजट बार, ऑडिट पूँछ |
 
+## MCP server
+
+`dsh-memento` एक केवल-पठन stdio **MCP सर्वर** (`dsh-memento-mcp`) भी देता है ताकि बाहरी MCP क्लाइंट (Claude, Codex, …) बिना harness के मेमोरी स्टोर खोज सकें। यह newline-delimited JSON (NDJSON) पर JSON-RPC 2.0 बोलता है — प्रति पंक्ति एक JSON ऑब्जेक्ट, कोई `Content-Length` फ़्रेमिंग नहीं।
+
+**केवल-पठन।** डेटाबेस `node:sqlite` के `readOnly: true` से खुलता है (कोई माइग्रेशन नहीं, कोई WAL लेखन नहीं, recall-count में वृद्धि नहीं); अगर फ़ाइल मौजूद नहीं है तो क्रैश के बजाय खाली परिणाम मिलते हैं।
+
+| टूल | उद्देश्य |
+|---|---|
+| `memory_search` | `{query, limit?}` → क्रमबद्ध प्रविष्टियाँ (retrieval Provider seam से केस-इनसेंसिटिव सबस्ट्रिंग) |
+| `memory_stats` | `{}` → `{total, namespaces}` प्रविष्टि गणना + track/scope अवलोकन |
+
+सीधे चलाएँ:
+
+```sh
+node bin/mcp-server.mjs
+# या, npm install के बाद: npx dsh-memento-mcp
+```
+
+डेटाबेस पथ `$DSH_MEMENTO_DB_PATH` है (निरपेक्ष, या `$DSH_HOME` के सापेक्ष); डिफ़ॉल्ट `$DSH_HOME/dsh-memento/memory.db`।
+
+Claude Desktop (`claude_desktop_config.json`) उदाहरण:
+
+```json
+{
+  "mcpServers": {
+    "dsh-memento": {
+      "command": "npx",
+      "args": ["-y", "dsh-memento-mcp"],
+      "env": {
+        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
+      }
+    }
+  }
+}
+```
+
+सर्वर केवल-पठन है: कोई नेटवर्क नहीं, कोई लेखन नहीं, कोई अनुमोदन द्वार नहीं — केवल खोज और आँकड़े।
+
 ## How it's different
 
 | Plugin | यह क्या है | dsh-memento का अंतर |

package/README.md

@@ -83,6 +83,7 @@ All tunables are Schemastery `Config` fields (changeable from cordis.yml). Inval
 | `recall.snippetCap` | `5` | `memory_recall` snippets per session |
 | `recall.snippetChars` | `300` | `memory_recall` snippet characters |
 | `recall.windowDays` | `30` | `memory_recall` recency window in days |
+| `retrieval.vector` | `false` | Semantic recall switch: `true` enables `memory_recall` vector recall (fake hash embedding) when an embedding provider is available; otherwise degrades to substring |
 | `panelEntriesLimit` | `200` | Web panel entries page size |
 | `panelAuditLimit` | `20` | Web panel audit rows by default |
 | `auditRetentionDays` | `0` | Audit retention (0 = keep forever) |
@@ -99,6 +100,44 @@ All tunables are Schemastery `Config` fields (changeable from cordis.yml). Inval
 | `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
 | web panel | client drawer | Read-only: browse entries, search, budget bars, audit tail |
 
+## MCP server
+
+`dsh-memento` ships a read-only stdio **MCP server** (`dsh-memento-mcp`) so external MCP clients (Claude, Codex, …) can search the memory store without a harness. It speaks JSON-RPC 2.0 over newline-delimited JSON (NDJSON) — one JSON object per line, no `Content-Length` framing.
+
+**Read-only.** The database is opened with `node:sqlite` `readOnly: true` (no migrations, no WAL writes, no recall-count bump); a missing database returns empty results instead of crashing.
+
+| Tool | Purpose |
+|---|---|
+| `memory_search` | `{query, limit?}` → ranked entries (case-insensitive substring via the retrieval Provider seam) |
+| `memory_stats` | `{}` → `{total, namespaces}` entry count + per-track/scope overview |
+
+Run it directly:
+
+```sh
+node bin/mcp-server.mjs
+# or, after npm install: npx dsh-memento-mcp
+```
+
+The database path is `$DSH_MEMENTO_DB_PATH` (absolute, or relative to `$DSH_HOME`); it defaults to `$DSH_HOME/dsh-memento/memory.db`.
+
+Claude Desktop (`claude_desktop_config.json`) example:
+
+```json
+{
+  "mcpServers": {
+    "dsh-memento": {
+      "command": "npx",
+      "args": ["-y", "dsh-memento-mcp"],
+      "env": {
+        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
+      }
+    }
+  }
+}
+```
+
+The server is read-only: no network, no writes, no approval gate — search and stats only.
+
 ## How it's different
 
 | Plugin | What it is | dsh-memento's difference |

package/README.pt.md

@@ -82,6 +82,7 @@ Todos os parâmetros são campos Schemastery `Config` (alteráveis pelo cordis.y
 | `recall.snippetCap` | `5` | Fragmentos por sessão no `memory_recall` |
 | `recall.snippetChars` | `300` | Caracteres de fragmento no `memory_recall` |
 | `recall.windowDays` | `30` | Janela de recência em dias do `memory_recall` |
+| `retrieval.vector` | `false` | Interruptor de recuperação semântica: `true` ativa a recuperação vetorial do `memory_recall` (embedding de hash falso) quando há um provedor de embedding; caso contrário degrada para substring |
 | `panelEntriesLimit` | `200` | Tamanho de página de entradas do painel web |
 | `panelAuditLimit` | `20` | Linhas de auditoria do painel web por padrão |
 | `auditRetentionDays` | `0` | Retenção de auditoria (0 = manter para sempre) |
@@ -98,6 +99,44 @@ Todos os parâmetros são campos Schemastery `Config` (alteráveis pelo cordis.y
 | `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
 | web panel | client drawer | Somente leitura: navegar entradas, buscar, barras de orçamento, cauda de auditoria |
 
+## MCP server
+
+O `dsh-memento` inclui um **servidor MCP** stdio somente-leitura (`dsh-memento-mcp`) para que clientes MCP externos (Claude, Codex, …) pesquisem o armazenamento de memória sem o harness. Ele fala JSON-RPC 2.0 sobre JSON delimitado por novas linhas (NDJSON): um objeto JSON por linha, sem enquadramento `Content-Length`.
+
+**Somente leitura.** O banco é aberto com `readOnly: true` do `node:sqlite` (sem migrações, sem gravações WAL, sem incremento do contador de recall); um banco ausente retorna resultados vazios em vez de falhar.
+
+| Ferramenta | Propósito |
+|---|---|
+| `memory_search` | `{query, limit?}` → entradas ordenadas (substring sem distinção de maiúsculas via o seam do Provider de recuperação) |
+| `memory_stats` | `{}` → `{total, namespaces}` contagem de entradas + visão geral por track/scope |
+
+Execução direta:
+
+```sh
+node bin/mcp-server.mjs
+# ou, após npm install: npx dsh-memento-mcp
+```
+
+O caminho do banco é `$DSH_MEMENTO_DB_PATH` (absoluto, ou relativo a `$DSH_HOME`); padrão `$DSH_HOME/dsh-memento/memory.db`.
+
+Exemplo para o Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dsh-memento": {
+      "command": "npx",
+      "args": ["-y", "dsh-memento-mcp"],
+      "env": {
+        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
+      }
+    }
+  }
+}
+```
+
+O servidor é somente-leitura: sem rede, sem gravações, sem porta de aprovação — apenas busca e estatísticas.
+
 ## How it's different
 
 | Plugin | O que é | A diferença do dsh-memento |

package/README.zh.md

@@ -82,6 +82,7 @@ dsh --profile web --dump-config | grep -A3 'id: memento'
 | `recall.snippetCap` | `5` | `memory_recall` 每个会话的片段数 |
 | `recall.snippetChars` | `300` | `memory_recall` 片段字符数 |
 | `recall.windowDays` | `30` | `memory_recall` 近期窗口天数 |
+| `retrieval.vector` | `false` | 语义召回开关：`true` 且探测到嵌入 provider 时 `memory_recall` 走向量召回（伪嵌入），否则优雅降级回 substring |
 | `panelEntriesLimit` | `200` | Web 面板条目分页大小 |
 | `panelAuditLimit` | `20` | Web 面板默认审计行数 |
 | `auditRetentionDays` | `0` | 审计保留天数（0 = 永久保留） |
@@ -98,6 +99,44 @@ dsh --profile web --dump-config | grep -A3 'id: memento'
 | `/memory` | command | `list` · `query` · `add` · `remove` · `consolidate` · `proposals` · `budgets` · `audit` · `export` · `import <path>` · `adapters` |
 | web panel | client drawer | 只读：浏览条目、搜索、预算条、审计尾部 |
 
+## MCP server
+
+`dsh-memento` 附带一个只读 stdio **MCP 服务器**（`dsh-memento-mcp`），让外部 MCP 客户端（Claude、Codex 等）无需 harness 即可检索记忆库。它通过 newline-delimited JSON（NDJSON）承载 JSON-RPC 2.0——每行一个 JSON 对象，不支持 `Content-Length` 分帧。
+
+**只读。** 数据库以 `node:sqlite` 的 `readOnly: true` 打开（不跑迁移、不写 WAL、不 bump recall-count）；库文件不存在时返回空结果而非崩溃。
+
+| 工具 | 用途 |
+|---|---|
+| `memory_search` | `{query, limit?}` → 排序后的条目（经检索 Provider seam 的大小写不敏感子串检索） |
+| `memory_stats` | `{}` → `{total, namespaces}` 条目总数 + 按轨道/作用域概览 |
+
+直接运行：
+
+```sh
+node bin/mcp-server.mjs
+# 或 npm 安装后：npx dsh-memento-mcp
+```
+
+数据库路径取自 `$DSH_MEMENTO_DB_PATH`（绝对路径，或相对 `$DSH_HOME`）；默认为 `$DSH_HOME/dsh-memento/memory.db`。
+
+Claude Desktop（`claude_desktop_config.json`）配置示例：
+
+```json
+{
+  "mcpServers": {
+    "dsh-memento": {
+      "command": "npx",
+      "args": ["-y", "dsh-memento-mcp"],
+      "env": {
+        "DSH_MEMENTO_DB_PATH": "/home/you/.dsh/dsh-memento/memory.db"
+      }
+    }
+  }
+}
+```
+
+服务器只读：无网络、无写入、无审批门——仅检索与统计。
+
 ## How it's different
 
 | Plugin | 是什么 | dsh-memento 的差异 |

package/bin/mcp-server.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// dsh-memento stdio MCP server launcher. Reads the memory database read-only
+// and serves memory_search / memory_stats over newline-delimited JSON-RPC 2.0
+// on stdio. No harness, no network, no write path — the database is opened
+// with node:sqlite readOnly:true and a missing file yields empty results.
+//
+// Database path: $DSH_MEMENTO_DB_PATH (absolute, or relative to $DSH_HOME);
+// defaults to $DSH_HOME/dsh-memento/memory.db (falls back to ~/.dsh).
+import { readFileSync } from 'node:fs'
+import { resolveDbPath } from '../lib/store.mjs'
+import { createMcpServer, ReadOnlyMemoryStore, runStdioServer } from '../lib/mcp.mjs'
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const dbPath = resolveDbPath(process.env.DSH_MEMENTO_DB_PATH ?? '')
+const store = new ReadOnlyMemoryStore(dbPath)
+const server = createMcpServer({ store, version: pkg.version })
+
+runStdioServer(server)

package/index.mjs

@@ -43,6 +43,8 @@ import { renderSnapshot, visibleEntries, visibleProposals } from './lib/snapshot
 import { openMemoryStore, resolveDbPath } from './lib/store.mjs'
 import { workspaceKeyOf, agentKeyOf } from './lib/workspace.mjs'
 import { extractEventText } from './lib/extract.mjs'
+import { EmbeddingProviderRegistry, FakeEmbeddingProvider } from './lib/embedding.mjs'
+import { RetrievalProviderRegistry, SubstringRetriever, VectorRetriever, detectVectorBackend } from './lib/retrieval.mjs'
 
 /**
  * @typedef {import('./types.js').MemoryEntry} MemoryEntry
@@ -55,6 +57,7 @@ import { extractEventText } from './lib/extract.mjs'
  * @typedef {object} StoreHandle - ctx.memory 依赖的 Provider 面。
  * @property {(filter?: {track?: string, scope?: string, text?: string, limit?: number}) => MemoryQueryResult} queryEntries
  * @property {() => MemoryEntry[]} listEntries
+ * @property {(ids: string[]) => void} bumpRecall
  * @property {(track: string, scope: string, match: string, opts?: {agentKey?: string, workspaceKey?: string}) => MemoryEntry[]} matchCandidates
  * @property {(track: string, scope: string) => number} usage
  * @property {(input: object) => MemoryEntry} insertEntry
@@ -91,6 +94,7 @@ import { extractEventText } from './lib/extract.mjs'
  * @property {number} [commandListLimit]
  * @property {number} [commandAuditLimit]
  * @property {{historyLimitDefault?: number, snippetCap?: number, snippetChars?: number, windowDays?: number}} [recall]
+ * @property {{vector?: boolean}} [retrieval]
  * @property {number} [panelEntriesLimit]
  * @property {number} [panelAuditLimit]
  * @property {number} [auditRetentionDays]
@@ -145,6 +149,8 @@ export const DEFAULT_SNAPSHOT_ORDER = -50
  * @property {number} [commandAuditLimit] /memory audit 单次渲染审计行上限（默认 10）。
  * @property {{historyLimitDefault?: number, snippetCap?: number, snippetChars?: number, windowDays?: number}} [recall]
  *   memory_recall 历史段默认值（默认 8/5/300/30）。
+ * @property {{vector?: boolean}} [retrieval] 语义召回开关（默认 false：substring 主路径；
+ *   true 且探测到 embedding provider 时 memory_recall 走向量召回，否则优雅降级回 substring）。
  * @property {number} [panelEntriesLimit] 面板条目页上限与钳制（默认 200）。
  * @property {number} [panelAuditLimit] 面板审计默认条数（默认 20；上限 200 为协议常量）。
  * @property {number} [auditRetentionDays] 审计保留天数（默认 0 = 不限）。
@@ -177,6 +183,9 @@ export const Config = Schema.object({
     snippetChars: Schema.number().default(300),
     windowDays: Schema.number().default(30),
   }),
+  retrieval: Schema.object({
+    vector: Schema.boolean().default(false),
+  }),
   panelEntriesLimit: Schema.number().default(200),
   panelAuditLimit: Schema.number().default(20),
   auditRetentionDays: Schema.number().default(0),
@@ -656,6 +665,9 @@ export function apply(ctx, /** @type {PluginConfig} */ config = {}) {
       snippetChars: config.recall?.snippetChars ?? 300,
       windowDays: config.recall?.windowDays ?? 30,
     },
+    retrieval: {
+      vector: config.retrieval?.vector ?? false,
+    },
     panelEntriesLimit: config.panelEntriesLimit ?? 200,
     panelAuditLimit: config.panelAuditLimit ?? 20,
     auditRetentionDays: config.auditRetentionDays ?? 0,
@@ -731,6 +743,21 @@ export function apply(ctx, /** @type {PluginConfig} */ config = {}) {
     ctx.effect(() => adapters.register(adapter), `dsh-memento.adapter.${adapter.id}`)
   }
 
+  // embedding Provider seam（ctx.memoryEmbedding）：注册表 + 默认确定性伪嵌入
+  // Provider（零依赖，接口级演示；真实嵌入由可选 provider 注册）。register 可逆，
+  // 经 ctx.effect 随插件生命周期自动回收。
+  const embeddings = new EmbeddingProviderRegistry()
+  ctx.provide('memoryEmbedding', embeddings)
+  ctx.effect(() => embeddings.register(new FakeEmbeddingProvider()), 'dsh-memento.embedding.fake-hash')
+
+  // retrieval Provider seam（ctx.memoryRetrieval）：内置 substring 检索器（零依赖
+  // 主路径）+ 可选 vector 检索器。vector 仅当 Config.retrieval.vector=true 且探测到
+  // embedding provider 时启用；否则优雅降级回 substring（retriever 保持 null）。
+  const retrievers = new RetrievalProviderRegistry()
+  ctx.provide('memoryRetrieval', retrievers)
+  ctx.effect(() => retrievers.register(new SubstringRetriever()), 'dsh-memento.retrieval.substring')
+  const resolvedRetriever = resolved.retrieval.vector === true ? setupVectorRetriever(ctx, retrievers, embeddings) : null
+
   // 审批 answerer：认领本插件的记忆写请求并按粒度策略裁决（writePolicies 精确键 >
   // track/scope > 全局 writePolicy；prepend 保证 auto/off 的确定性先于 UI answerer；
   // 会话级 never 策略在审批服务内部先裁决，任何 answerer 都无法绕过）。
@@ -797,7 +824,7 @@ export function apply(ctx, /** @type {PluginConfig} */ config = {}) {
   // V2 观察面：/memory 命令（用户触发）、memory_recall 工具、面板 JSON 路由。
   // commands/webServer 为可选服务，缺失（headless）自动跳过。
   registerCommands(ctx, service)
-  ctx.tools.register(/** @type {import('@deepseek-ai/dsh-tools').ToolDefinition} */ (makeMemoryRecallTool(service, ctx, resolved.recall, resolved.language)))
+  ctx.tools.register(/** @type {import('@deepseek-ai/dsh-tools').ToolDefinition} */ (makeMemoryRecallTool(service, ctx, resolved.recall, resolved.language, resolvedRetriever)))
   registerWebRoutes(ctx, service, resolved)
 
   // auto-capture：监听会话事件火线，压缩结束后生成记忆提案（只落提案，不写记忆、不调模型）。
@@ -807,6 +834,24 @@ export function apply(ctx, /** @type {PluginConfig} */ config = {}) {
   })
 }
 
+/**
+ * 按 Config.retrieval.vector 探测并装配 vector 检索器：探测到 embedding provider
+ * 才注册 VectorRetriever 并返回之；否则优雅降级（返回 null，调用方回退 substring
+ * 主路径），绝不响亮失败——vector 是可选后端，缺 embedding 不构成配置错误。
+ * @param {import('@deepseek-ai/cordis').Context} ctx - Cordis 上下文（注册 effect）。
+ * @param {import('./lib/retrieval.mjs').RetrievalProviderRegistry} retrievers - 检索注册表。
+ * @param {import('./lib/embedding.mjs').EmbeddingProviderRegistry} embeddings - 嵌入注册表。
+ * @returns {import('./lib/retrieval.mjs').RetrievalProvider | null} vector 检索器或 null（降级）。
+ */
+function setupVectorRetriever(ctx, retrievers, embeddings) {
+  const embedding = embeddings.get('fake-hash')
+  const probe = detectVectorBackend({ embedding })
+  if (!probe.available) return null
+  const retriever = new VectorRetriever({ embedding })
+  ctx.effect(() => retrievers.register(retriever), 'dsh-memento.retrieval.vector')
+  return retriever
+}
+
 /**
  * auto-capture 提案生成：缓存每会话最近的 compaction/summary 文本，compaction/end
  * 成功时截断落 proposals 表（(session_id, kind) 幂等；pending 满则弃新）。
@@ -1439,9 +1484,11 @@ function renderEntryLine(/** @type {{track: string, scope: string, workspaceKey?
  * @param {import('@deepseek-ai/cordis').Context} ctx - Cordis 上下文（查 sessionQuery）。
  * @param {{historyLimitDefault: number, snippetCap: number, snippetChars: number, windowDays: number}} recall - Config.recall（默认值）。
  * @param {'en'|'zh'} [language] - 'en' | 'zh'。
+ * @param {import('./lib/retrieval.mjs').RetrievalProvider | null} [retriever] - 语义检索器；
+ *   null = 默认 substring 主路径（走 service.query 的 SQL instr）。
  * @returns {object} 工具定义。
  */
-export function makeMemoryRecallTool(service, ctx, recall, language = 'en') {
+export function makeMemoryRecallTool(service, ctx, recall, language = 'en', retriever = null) {
   const description = language === 'zh'
     ? [
       '对记忆与会话历史的两段式召回：返回 (1) dsh-memento 库中与查询匹配的有界记忆条目，以及 (2) 经 session-query 服务的近期会话历史匹配。',
@@ -1529,15 +1576,13 @@ export function makeMemoryRecallTool(service, ctx, recall, language = 'en') {
     },
     execute: /** @type {(args: any, exec: any) => Promise<any>} */ (async (args, exec) => {
       exec.signal.throwIfAborted()
-      const memory = service.query(
-        { text: args.query, limit: args.memoryLimit ?? 10 },
-        {
-          sessionId: exec.agent?.session?.id,
-          session: exec.agent?.session,
-          // 与 memory 工具一致：会话内召回按可见集过滤（共享 + 本 agent）。
-          agentKey: agentKeyOf(/** @type {string | undefined} */ (exec.agent?.session?.header?.agentPreset)),
-        },
-      )
+      const sessionId = /** @type {string | undefined} */ (exec.agent?.session?.id)
+      const session = /** @type {MemorySessionLike | null | undefined} */ (exec.agent?.session ?? null)
+      const agentKey = agentKeyOf(/** @type {string | undefined} */ (exec.agent?.session?.header?.agentPreset))
+      const limit = args.memoryLimit ?? 10
+      const memory = retriever === null
+        ? service.query({ text: args.query, limit }, { sessionId, session, agentKey })
+        : recallViaRetriever(service, retriever, args.query, limit, { sessionId, session, agentKey })
       const history = await recallHistory(
         ctx,
         args.query,
@@ -1561,6 +1606,40 @@ export function makeMemoryRecallTool(service, ctx, recall, language = 'en') {
   })
 }
 
+/**
+ * 语义召回路径（retrieval seam 的 Consumer 面）：可见条目 → 检索器排序 → 召回计数
+ * + 审计。与 service.query 的子串路径对齐：命中页召回计数 +1（bumpRecall）、带
+ * sessionId 时记 recalled 审计行。可见集 = 会话 cwd 工作区层 + 共享/本 agent 层
+ * （与快照 visibleEntries 同语义）。
+ * @param {MemoryService} service - ctx.memory（提供 store）。
+ * @param {import('./lib/retrieval.mjs').RetrievalProvider} retriever - 语义检索器。
+ * @param {string} query - 检索词。
+ * @param {number} limit - 返回上限。
+ * @param {{sessionId?: string, session?: MemorySessionLike | null, agentKey: string}} opts - {sessionId, session, agentKey}。
+ * @returns {MemoryQueryResult}。
+ */
+function recallViaRetriever(service, retriever, query, limit, opts) {
+  const workspaceKey = workspaceKeyOf(/** @type {string | undefined} */ (opts.session?.header?.cwd))
+  const entries = visibleEntries(
+    /** @type {Array<{id: string, track: string, scope: string, workspaceKey: string, agentKey: string, text: string, createdAt: number}>} */ (service.store.listEntries()),
+    workspaceKey,
+    opts.agentKey,
+  )
+  const ranked = /** @type {MemoryEntry[]} */ (retriever.retrieve(query, entries))
+  const shown = ranked.slice(0, limit)
+  service.store.bumpRecall(shown.map((entry) => entry.id))
+  if (opts.sessionId !== undefined) {
+    service.store.auditAppend({
+      action: 'recalled',
+      text: query,
+      outcome: 'ok',
+      source: /** @type {string} */ (service.sourceLabel),
+      sessionId: opts.sessionId,
+    })
+  }
+  return { entries: shown, total: ranked.length, truncated: ranked.length > shown.length }
+}
+
 /**
  * 近期会话历史召回（sessionQuery 可选；rc.6 记录形状 = {header:{id}}，事件为元数据记录）。
  * 服务端下推：filterSessions 以会话 cwd（原值直传，harness 按存储值比较）与

package/lib/constants.mjs

@@ -56,6 +56,8 @@ export const ERROR_CODES = {
   STORE_UNSUPPORTED_VERSION: 'STORE_UNSUPPORTED_VERSION',
   ADAPTER_NOT_FOUND: 'ADAPTER_NOT_FOUND',
   ADAPTER_PAYLOAD: 'ADAPTER_PAYLOAD',
+  EMBEDDING_NOT_FOUND: 'EMBEDDING_NOT_FOUND',
+  RETRIEVAL_NOT_FOUND: 'RETRIEVAL_NOT_FOUND',
 }
 
 /** 会话事件名（SessionEventMap 声明合并的词汇表；运行时按已知类型自适应派发）。 */