@zooique/memora 3.0.1 → 5.0.0

package/README.en.md

@@ -1,4 +1,4 @@
-# Memora
+# Memora
 
 > **Agent Memory Kernel with Governance** — Local-first, Private, Zero-dep. Not a framework, a kernel.
 
@@ -6,7 +6,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-22%20LTS-339933)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)
 [![Coverage](https://img.shields.io/badge/coverage-covered-brightgreen)](https://vitest.dev)
-[![Tests](https://img.shields.io/badge/tests-2700%2B%20passed-brightgreen)](https://vitest.dev)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://vitest.dev)
 [![Dependencies](https://img.shields.io/badge/runtime%20deps-0-yellowgreen)](package.json)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -17,7 +17,7 @@
 ## What problem are you facing?
 
 - **LLM forgets everything between sessions** — Your users remember what they said, your agent doesn't
-- **Existing memory solutions are either too heavy (framework-bound) or too shallow (CRUD only)** — No dedup, conflict detection, or write-time supersede
+- **Existing memory solutions are either too heavy (framework-bound) or too shallow (CRUD only)** — No write-time supersede: either decay-only forgetting, or old and new memories coexist and contradict each other
 - **Memory and persona are tangled** — Switch personas and lose your history
 - **You don't want to send data to the cloud** — Need a local, private memory layer with zero external dependencies
 
@@ -25,7 +25,7 @@
 
 Memora is an **Agent memory kernel** — framework-agnostic, cloud-independent, focused on one thing: **giving your agent cross-session, cross-topic long-term memory that stays clean.**
 
-"Clean" means: semantic deduplication, conflict detection, write-time supersede, and last-used refresh (accessedAt, used for ordering) — no importance weighting, and not just stuffing history into the context window.
+"Clean" means: write-time supersede (soft `supersededBy` pointer, traceable) and last-used refresh (accessedAt, used for ordering) — no importance weighting, and not just stuffing history into the context window. **Governance happens at write time only**: there is no subscription-style post-hoc sweep (dedup / conflict detection / related suggestions were retired as a whole in 5.0.0 — see the Core Capabilities table).
 
 ```typescript
 import { Agent, createProviderFromConfig } from '@zooique/memora';
@@ -50,11 +50,6 @@ for await (const chunk of agent.chat('I love TypeScript')) {
 // Next session — the LLM can call search_memories to retrieve this memory
 const reply = await agent.chatSync('What language do I like?');
 
-// Memory governance — dedup / conflict detection / source health
-await agent.governance.deduplicate();
-await agent.governance.detectConflicts();
-const health = agent.governance.sourceHealth();
-
 await agent.close();
 ```
 
@@ -66,14 +61,14 @@ await agent.close();
 
 | | Memora | Vector memory libs (agent-memory, MemStack) | Framework-builtin memory (Mastra, LangGraph) |
 |---|---|---|---|
-| **Memory governance** | ✅ Dedup+conflict+write-time supersede | ⚠️ Decay only or none | ⚠️ Partial |
+| **Memory governance** | ✅ Write-time supersede (soft `supersededBy`, traceable) | ⚠️ Decay only or none | ⚠️ Partial |
 | **Framework lock-in** | ✅ Zero — pure kernel | ✅ Standalone | ❌ Tied to framework |
 | **Data privacy** | ✅ 100% local | ✅ Local | ⚠️ Partially cloud |
 | **Runtime deps** | ✅ Zero (node:* only) | ❌ SQLite / better-sqlite3 | ❌ Heavy |
 | **Persona/memory separation** | ✅ Role-pack boundary discipline | ❌ No persona concept | ⚠️ Simple prompt |
 | **Embeddable** | ✅ Any Node.js host | ✅ Standalone lib | ❌ Framework-internal |
 
-**One-line positioning**: If you want a **framework-agnostic, governance-capable, zero-dependency** memory layer, Memora is currently the only option on npm.
+**One-line positioning**: If you want a **framework-agnostic, governance-capable (write-time supersede), zero-dependency** memory layer, Memora is currently the only option on npm.
 
 ---
 
@@ -85,7 +80,7 @@ await agent.close();
 
 Memora is a **brain kernel that cannot run standalone** — it has interfaces but no "form." A CLI, WebUI, desktop sprite, or novel generator can be its "host." The host gives it a body (UI), blood vessels (Provider), and neural circuits (event loops).
 
-> **Version positioning (v3.0.0)**: **Node.js-only · Zero third-party runtime deps Agent kernel**. v3.0.0 is the first stable baseline after architecture convergence.
+> **Version positioning (v5.0.0)**: **Node.js-only · Zero third-party runtime deps Agent kernel**. **v5.0.0 (current)**: major public surface pruning (23 exports + 32 public members + 3 events removed) + multi-project shape finalized (one Agent = one project) + three never-live chains retired (goal-drift detection / memory governance facade / checkpoint fake-flushing) + a `node:*` built-in SQLite storage implementation added (`createNodeSqliteStorage`) — see the [upgrade guide](docs/memora-升级指南-4.x-到-5.0.0.md) for per-item migration. **v4.0.0**: public export surface collapsed (54 exports removed; full list in the `[4.0.0]` section of [CHANGELOG](./CHANGELOG.md)) + `agent.memory.search()` removed (`searchByKeyword()` is the sole entry).
 
 ---
 
@@ -95,7 +90,7 @@ Memora is a **brain kernel that cannot run standalone** — it has interfaces bu
 |-----------|-------------|
 | **Long-term Memory** | Cross-session, cross-topic memory persistence with tool-based recall (`search_memories`; no automatic injection) |
 | **Memory Search Tool** | Keyword-only retrieval (`search_memories`), refreshes `accessedAt` on hit (semantic vector channel removed via B0, 2026-09-18) |
-| **Memory Governance** | Write-time supersede + last-used refresh (`accessedAt` used for ordering; no importance weighting) + semantic dedup + conflict detection via `agent.governance` facade (dedup / conflict judged by LLM) |
+| **Memory Governance** | **Write-time governance only**: write-time supersede + last-used refresh (`accessedAt` used for ordering; no importance weighting). Subscription-style post-hoc governance (dedup / conflict detection / related suggestions) was retired as a whole in 5.0.0 |
 | **Agent-Persona Separation** | Agent is a pure memory engine; persona is a personality vessel. Switch personas without losing memories |
 | **Unified Memory Model** | Everything is a "Memory" primitive, distinguished by open-string `source` — no closed enums |
 | **Domain-agnostic** | Same architecture, different memory configs → different domains |
@@ -119,8 +114,7 @@ import { Agent, createProviderFromConfig } from '@zooique/memora';
 // Host responsibility: create an LLM Provider
 // Works with any OpenAI Chat Completions-compatible service
 // createProviderFromConfig is the canonical entry (baseUrl+model+apiKey → validated creation; provider
-// selection is the host's responsibility). createLlmProvider(loadConfig()) is only a config-file convenience
-// (active selection resolved inside the kernel) when you delegate the whole Config to it.
+// selection is the host's responsibility).
 const provider = createProviderFromConfig('primary', {
   provider: 'openaiCompatible',
   apiKey: process.env.LLM_API_KEY!,
@@ -159,15 +153,15 @@ const reply = await agent.chatSync('What language do I like?');
 // Search memories (keyword-only; semantic vector channel removed via B0, 2026-09-18), limit is a number
 const hits = await agent.memory.searchByKeyword('TypeScript preference', 5);
 
-// Governance (exposed via agent.governance facade, LLM-judged)
-const report = await agent.governance.deduplicate();
-console.log(`Deduplicated ${report.deduplicatedCount} memories`);
-
-const conflicts = await agent.governance.detectConflicts();
+// Source health diagnosis (pure computation, no LLM): sources are discovered dynamically
+// via getAllSources(); per-source count / days since last access
+const stats = agent.memory.stats();
+console.log(stats.bySource);
 
-// Source health diagnosis (pure computation, no LLM): per-source count / days since last access (score retired → factual observation only)
-const health = agent.governance.sourceHealth();
-console.log(health?.sources);
+// Write-time governance is handled by supersede: a new memory replaces the old one and
+// leaves a soft `supersededBy` pointer (nothing is deleted, history stays traceable).
+// Subscription-style post-hoc governance (dedup / conflict detection / related
+// suggestions) was retired as a whole in 5.0.0 - see the note in API reference §4.
 ```
 
 ### Cleanup
@@ -189,8 +183,8 @@ await agent.close();
 │  ┌──────────────────────────────────────────┐               │
 │  │  Memora Kernel (Agent)                   │               │
 │  │  - chat(input) → streaming response      │               │
-│  │  - Keyword-only search (semantic vector channel removed via B0)│               │
-│  │  - Memory governance (dedup/conflict/supersede) │         │
+│  │  - Keyword-only search                   │               │
+│  │  - Write-time governance (supersede)     │               │
 │  │  - Role pack matching / Skill matching   │               │
 │  │  - Tool registration / execution         │               │
 │  │  - Session archive / round persistence   │               │
@@ -204,10 +198,25 @@ The kernel interacts with the outside world through interfaces. Hosts inject imp
 
 | Interface | Responsibility | Built-in Implementation |
 |-----------|---------------|------------------------|
-| `IMemoryStorage` | Memory CRUD + search + query by source | `InMemoryStorage` |
+| `IMemoryStorage` | Memory CRUD + search + query by source | Built-in in-memory default (placeholder, non-persistent; internal class, not on the public surface — PUB-API-PRUNE-2) + optional persistent impl `createNodeSqliteStorage(dbPath)` (built-in `node:sqlite`, zero third-party deps) | Host picks the backend: create SQLite via the kernel factory, or implement its own (JSON / own SQLite) |
 | `ISessionStore` | Session history persistence | None (host implements) |
 | `ILogger` | Logging output | console fallback |
-| `ITracer` | Observability spans | `NOOP_TRACER` |
+| `ITracer` | Observability spans | Internal noop (not on the public surface; omit `tracer` for zero overhead) |
+
+### Multi-project and Agent boundaries (settled model)
+
+**One Agent binds to one project** — `projectPath` + one storage + one session domain. For multiple projects, the **host** creates one Agent instance per project; the kernel neither switches projects nor maintains a cross-project registry.
+
+| Dimension | Model |
+|-----------|-------|
+| One project (one Agent) | May own N sessions (`switchSession` / `switchToSession` / `forkSession`), but **only one runs at a time** |
+| N projects (N Agent instances) | Run **in parallel**, each with its own memory store / sessions / project lock |
+| Parallelism | **Counted by project, not by session** |
+| Sessions within a project | **Share one memory store** (search has no session filter) ⇒ experience carries across sessions |
+
+> **Trade-off (stated explicitly)**: this model deliberately does **not** mirror the mainstream "one session = one Agent instance" design. The cost: **two sessions cannot run in parallel within the same project** (mainstream tools just open two terminals). This is known and accepted, tracked as `MULTI-SESS-1` (observation only) — it is revisited only if a real need for "two parallel tasks in one repo" appears.
+> **Rationale**: the memory store belongs to the **project**; a session is just a conversation thread inside it. Drawing the identity boundary at the project (not the session) is what lets experience carry across sessions.
+> See the [integration guide](docs/memora-接入指南.md) ("多项目怎么办") for wiring details and data layout.
 
 ## Project Structure
 
@@ -220,8 +229,8 @@ src/
 │   ├── assembler.ts  # Component assembler (pure factory)
 │   ├── contextManager.ts / contextPreparer.ts / toolExecutor.ts / toolRunner.ts ···
 │   ├── seed/         # Minimal execution loop (prepare → act/difficulty → reflect, incl. external task outer loop)
-│   └── managers/     # 16 specialized Managers/service classes (memoryInspector / memoryGovernance / roundSummaryGenerator / sessionManager / sessionArchiver / archiveCoordinator / workProjection / textPolishManager / chatLockManager, etc.)
-├── memory/           # Memory engine (IMemoryStorage + InMemoryStorage + keyword recall / fusion ranking / governance constants)
+│   └── managers/     # Specialized Managers/service classes (memoryInspector / roundSummaryGenerator / sessionManager / sessionArchiver / archiveCoordinator / workProjection / textPolishManager / chatLockManager, etc.)
+├── memory/           # Memory engine (IMemoryStorage + InMemoryStorage + optional SQLite store + keyword recall / supersede resolution)
 ├── role-pack/        # Role packs (manifest parsing + validator + strategyResolver + capability mapping)
 ├── skill/            # Skill management (global pool + role-pack binding, progressive disclosure + skillScriptRunner)
 ├── llm/              # LLM adapter layer (provider + openaiCompatible + factory)
@@ -251,15 +260,12 @@ src/
 
 | Metric | Value |
 |--------|-------|
-| Source | 117 production files (src/, zero third-party runtime deps) |
-| Tests | Dual vitest suites (kernel + host), run by the root vitest config (100+ files) |
-| Tests Passing | 2700+ passed / 1 skipped |
-| Statement Coverage | 90.65% |
-| Branch Coverage | 84.83% |
-| Function Coverage | 92.41% |
-| Line Coverage | 91.79% |
+| Source | All production files under src/ (zero third-party runtime deps; no count listed — any count is a point-in-time snapshot) |
+| Tests | Dual vitest suites (kernel + host), run by the root vitest config |
+| Tests Passing | All passing (pass/skip counts as measured by pre-release CI — point-in-time snapshots, not recorded here) |
+| Test Coverage | Statement / branch / function / line coverage: run `npm run test:cov` for current values (no percentages recorded here — they are point-in-time snapshots) |
 | Runtime Dependencies | **0** |
-| Architecture Decision Records | 26 ADRs |
+| Architecture Decision Records | In-repo `.trae/decisions/` directory (see its `README.md` for the index; no count listed here — any count is a point-in-time snapshot) |
 
 ## Development
 
@@ -274,6 +280,7 @@ npm run build        # Compile to dist/
 ## Documentation
 
 - [Integration Guide](docs/memora-接入指南.md) — Complete host developer onboarding manual (Chinese)
+- [**Upgrading from 4.x to 5.0.0**](docs/memora-升级指南-4.x-到-5.0.0.md) — What was removed and how to migrate each item (Chinese; required for the major upgrade)
 - [API Reference](docs/memora-api-reference.md) — Public API quick reference (Chinese)
 - [Config Example](config.example.json) — LLM / Security config template
 
@@ -281,13 +288,13 @@ npm run build        # Compile to dist/
 
 [memora-vscode](https://github.com/zooique/memora/tree/main/hosts/memora-vscode) — The VS Code extension host (primary host), demonstrating a complete Memora integration: JSON file persistence (`.memora/memories.json`), keyword-only search, role pack management, and memory views.
 
-## Why Memora?
+## Why not cloud or framework memory?
 
 | | Memora | Cloud memory services | Framework memory modules |
 |---|---|---|---|
 | Data privacy | ✅ 100% local | ❌ Cloud-dependent | ⚠️ Varies |
 | Runtime deps | ✅ Zero | N/A (SaaS) | ❌ Heavy |
-| Memory lifecycle | ✅ Full (dedup/conflict/supersede) | ⚠️ Partial | ❌ CRUD only |
+| Memory lifecycle | ✅ Write-time supersede | ⚠️ Partial | ❌ CRUD only |
 | Domain-agnostic | ✅ Open-string source | ⚠️ Opinionated | ⚠️ Framework-locked |
 | Embeddable | ✅ Any Node.js host | ❌ API calls only | ⚠️ Framework-bound |
 | Relation graph | ✅ Built-in sidecar | ❌ Rare | ❌ Rare |

package/README.md

@@ -6,7 +6,7 @@
 [![Node.js](https://img.shields.io/badge/Node.js-22%20LTS-339933)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)
 [![Coverage](https://img.shields.io/badge/coverage-covered-brightgreen)](https://vitest.dev)
-[![Tests](https://img.shields.io/badge/tests-2700%2B%20passed-brightgreen)](https://vitest.dev)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://vitest.dev)
 [![Dependencies](https://img.shields.io/badge/runtime%20deps-0-yellowgreen)](package.json)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
 
@@ -17,7 +17,7 @@
 ## 你遇到了什么问题？
 
 - **LLM 每次对话都从零开始** — 用户记得上次聊过什么，Agent 不记得
-- **现有记忆方案要么太重（框架绑定）要么太浅（只有 CRUD）** — 缺少去重、冲突检测、写时取代等治理能力
+- **现有记忆方案要么太重（框架绑定）要么太浅（只有 CRUD）** — 缺少写时取代（supersede）这类确定性治理：要么只有衰减式遗忘，要么让新旧记忆并存互相打架
 - **记忆和角色混在一起** — 换个角色人格，历史记忆也跟着丢了
 - **数据不想上云** — 需要一个本地、私有、不依赖外部服务的记忆层
 
@@ -25,7 +25,7 @@
 
 Memora 是一个 **Agent 记忆内核**——不绑定任何框架，不依赖任何云服务，专注于一件事：**让 Agent 拥有跨会话、跨话题的长期记忆，并且记忆是干净的。**
 
-"干净"意味着：语义去重、冲突检测、写时取代（supersede）、命中即刷新最近使用（`accessedAt`，参与排序）——**不对记忆做重要度加权**，也不是简单地把历史堆进上下文窗口。
+"干净"意味着：写时取代（supersede，`supersededBy` 软指针，可回溯）、命中即刷新最近使用（`accessedAt`，参与排序）——**不对记忆做重要度加权**，也不是简单地把历史堆进上下文窗口。**治理只发生在写入那一刻**，不做订阅式的后备巡检（去重 / 冲突检测 / 关联推荐已于 5.0.0 整链退役，见「核心能力」表）。
 
 ```typescript
 import { Agent, createProviderFromConfig } from '@zooique/memora';
@@ -50,11 +50,6 @@ for await (const chunk of agent.chat('我喜欢 TypeScript')) {
 // 下次对话 — LLM 可自行调用 search_memories 取回这条记忆
 const reply = await agent.chatSync('我喜欢什么语言？');
 
-// 记忆治理 — 语义去重 / 冲突检测 / 来源健康诊断
-await agent.governance.deduplicate();
-await agent.governance.detectConflicts();
-const health = agent.governance.sourceHealth();
-
 await agent.close();
 ```
 
@@ -68,7 +63,7 @@ await agent.close();
 
 | | Memora | 向量记忆库 (agent-memory, MemStack) | 框架内置记忆 (Mastra, LangGraph) |
 |---|---|---|---|
-| **记忆治理** | ✅ 去重+冲突+写时取代 | ⚠️ 仅衰减或无治理 | ⚠️ 部分支持 |
+| **记忆治理** | ✅ 写时取代（可回溯） | ⚠️ 仅衰减或无治理 | ⚠️ 部分支持 |
 | **框架绑定** | ✅ 零绑定，纯内核 | ✅ 独立 | ❌ 绑定特定框架 |
 | **数据隐私** | ✅ 100% 本地 | ✅ 本地 | ⚠️ 部分云端 |
 | **运行时依赖** | ✅ 零（仅 node:*） | ❌ SQLite / better-sqlite3 | ❌ 重依赖 |
@@ -77,7 +72,7 @@ await agent.close();
 
 **一句话定位**：如果你想要一个**不绑定框架、有治理能力、零依赖**的 memory + agent 内核，Memora 有清晰的差异化——它不是一个记忆 server / CLI / MCP 工具，而是一个可嵌入宿主、含完整执行闭环（loop / 工具 / 上下文 / 角色包 / 记忆即摘要）的纯逻辑内核。
 
-> **生态定位（2026-09-21 实证）**：npm 上 agent 类包已分两轴——**引擎轴**（loop/工具执行：`@ownware/loom`、`@hbbio/nanoagent`、`@imzx/imzx`、`thoth-agent` 等）与**记忆层轴**（`@agentmemory/agentmemory`、`mem0`、`flair`、`honcho`、`engram`、`agentic-memory` 等）。Memora 同时触及两轴，但**具体组合无人占据**：① 引擎轴同等竞品均有运行时依赖或绑定特定 runtime（loom=7 deps、imzx=11 deps、nanoagent 绑定 bun），而 Memora 是**纯 Node 零第三方运行时依赖**；② 记忆层包（engram / agentic-memory 等）只做记忆，**不提供执行内核**；③ 引擎轴包（loom 等）只做**会话内**上下文 / checkpoint，**没有跨会话被治理的长期记忆**（内存治理：去重 / 冲突检测 / supersede 写时取代 / 角色包隔离）。**护城河 = 治理型长期记忆 + 角色包隔离，以纯 Node 零依赖、宿主内嵌形态交付**。引擎轴上有 [loom](https://www.npmjs.com/package/@ownware/loom) 这样的强对手，不应与其在「引擎」轴上对拼；竞争力聚焦在「被治理的记忆 + 角色包」这一 layer。
+> **生态定位（2026-09-21 实证）**：npm 上 agent 类包已分两轴——**引擎轴**（loop/工具执行：`@ownware/loom`、`@hbbio/nanoagent`、`@imzx/imzx`、`thoth-agent` 等）与**记忆层轴**（`@agentmemory/agentmemory`、`mem0`、`flair`、`honcho`、`engram`、`agentic-memory` 等）。Memora 同时触及两轴，但**具体组合无人占据**：① 引擎轴同等竞品均有运行时依赖或绑定特定 runtime（loom=7 deps、imzx=11 deps、nanoagent 绑定 bun），而 Memora 是**纯 Node 零第三方运行时依赖**；② 记忆层包（engram / agentic-memory 等）只做记忆，**不提供执行内核**；③ 引擎轴包（loom 等）只做**会话内**上下文 / checkpoint，**没有跨会话被治理的长期记忆**（治理 = supersede 写时取代 / 角色包隔离）。**护城河 = 确定性写时治理 + 角色包隔离，以纯 Node 零依赖、宿主内嵌形态交付**。引擎轴上有 [loom](https://www.npmjs.com/package/@ownware/loom) 这样的强对手，不应与其在「引擎」轴上对拼；竞争力聚焦在「被治理的记忆 + 角色包」这一 layer。
 
 > **可被复用去开发 Agent（是）**：Memora 生来就是**宿主注入型的内核库**——`Agent` 门面 + `loop` 执行闭环 + 工具注入接口（web_search / web_fetch / run_code / search_project）+ `createProviderFromConfig`（可接任意 OpenAI 兼容 LLM），任何 Node.js 宿主都能用它搭出**带记忆和角色的自有 Agent**（聊天框、桌面精灵、文档助理、运算 worker……）。这正是设计意图：它只有接口、没有形态，形态由宿主定义。唯一前提是宿主需提供持久化 / 沙箱 / UI 等外围（内核不内置 sink）。
 
@@ -91,7 +86,7 @@ await agent.close();
 
 Memora 是一个**无法独立运行**的智能大脑内核——它只有接口，没有"形态"。CLI、WebUI、桌面精灵、小说生成器都是它的"宿主"，宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
 
-> **版本定位（v3.0.0）**：**Node.js 专属 · 零第三方运行时依赖的 Agent 内核**。3.0.0 是架构收敛后的第一个稳定基线，API 与结构以 3.0.0 为准。
+> **版本定位（v5.0.0）**：**Node.js 专属 · 零第三方运行时依赖的 Agent 内核**。**5.0.0（当前）**：公开面大收面（删 23 个导出符号 + 32 个公开成员 + 3 个事件）+ 多项目形态定案（一个 Agent = 一个项目）+ 三套空转机制退役（目标漂移检测 / 记忆治理门面 / 检查点假落盘）+ SQLite 存储实现（`createNodeSqliteStorage`）——破坏性变更逐条改法见 [升级指南](docs/memora-升级指南-4.x-到-5.0.0.md)。**4.0.0**：导出面收敛（移除 54 个公共导出，逐条清单见 [CHANGELOG](./CHANGELOG.md) 的 `[4.0.0]` 区）+ `agent.memory.search()` 退役（唯一入口 `searchByKeyword()`）。
 
 ---
 
@@ -101,7 +96,7 @@ Memora 是一个**无法独立运行**的智能大脑内核——它只有接口
 |------|------|
 | **长期记忆沉淀** | 跨会话、跨话题的记忆持久化 + 工具化召回（`search_memories`；**不自动注入**） |
 | **记忆检索工具** | 纯关键词检索（`search_memories`），命中刷新 `accessedAt`（语义向量通道已随 B0 收编，2026-09-18） |
-| **记忆治理** | supersede 写时取代 + 命中刷新（`accessedAt` 参与排序，**不做重要度加权**）+ 语义去重 + 冲突检测，经 `agent.governance` 门面暴露（去重 / 冲突由 LLM 判断） |
+| **记忆治理** | 只有**写时治理**：supersede 写时取代 + 命中刷新（`accessedAt` 参与排序，**不做重要度加权**）。订阅式事后治理（去重 / 冲突检测 / 关联推荐）已于 5.0.0 整链退役 |
 | **Agent 与角色分离** | Agent 是纯记忆引擎，角色是人格载体。换角色不丢记忆 |
 | **统一记忆模型** | 一切统一为「记忆」，通过 `source` 开放字符串区分，无封闭枚举 |
 | **领域可插拔** | 同一套架构，加载不同记忆配置即可适配不同领域 |
@@ -123,8 +118,7 @@ npm install @zooique/memora
 import { Agent, createProviderFromConfig } from '@zooique/memora';
 
 // 宿主职责：创建 LLM Provider（兼容所有 OpenAI Chat Completions 协议的服务）
-// createProviderFromConfig 是唯一规范入口（baseUrl+model+apiKey → 校验后创建，provider 选择策略归宿主）；
-// createLlmProvider(loadConfig()) 仅当你把整份 Config 托管给内核时用作便利（active 选择在内核侧）。
+// createProviderFromConfig 是唯一规范入口（baseUrl+model+apiKey → 校验后创建，provider 选择策略归宿主）。
 const provider = createProviderFromConfig('primary', {
   provider: 'openaiCompatible',
   apiKey: process.env.LLM_API_KEY!,
@@ -163,15 +157,13 @@ const reply = await agent.chatSync('我喜欢什么语言？');
 // 搜索记忆（limit 为数字）
 const hits = await agent.memory.searchByKeyword('TypeScript 偏好', 5);
 
-// 记忆治理（经 agent.governance 门面委托暴露，LLM 判断）
-const report = await agent.governance.deduplicate();
-console.log(`去重 ${report.deduplicatedCount} 条`);
-
-const conflicts = await agent.governance.detectConflicts();
+// 来源分布（纯计算，不调 LLM）：逐 source 统计活跃记忆数
+const stats = agent.memory.stats();
+console.log(stats.bySource);
 
-// 来源健康诊断（纯计算，不调 LLM）：逐 source 统计数量 / 距最近访问天数（score 退役后仅存事实观测）
-const health = agent.governance.sourceHealth();
-console.log(health?.sources);
+// 写时治理由 supersede（写时取代）承担：新记忆写入时取代旧记忆，旧记忆留
+// supersededBy 软指针（不删除，可回溯）。订阅式事后治理（去重 / 冲突检测 /
+// 关联推荐）已于 5.0.0 整链退役，详见 API 参考手册 §四 注记。
 ```
 
 ### 关闭
@@ -194,7 +186,7 @@ await agent.close();
 │  │  Memora 内核（Agent）                    │               │
 │  │  - chat(input) → 流式响应                │               │
 │  │  - 纯关键词记忆检索（search_memories）    │               │
-│  │  - 记忆治理机制（去重/冲突/写时取代）   │               │
+│  │  - 记忆治理机制（supersede 写时取代）   │               │
 │  │  - 角色 / 技能匹配（渐进披露）          │               │
 │  │  - 工具注册 / 工具执行 / 反思重试        │               │
 │  │  - 会话归档 / 轮次持久化                │               │
@@ -208,10 +200,25 @@ await agent.close();
 
 | 接口 | 职责 | 内置实现 | 宿主注意 |
 |------|------|----------|----------|
-| `IMemoryStorage` | 记忆 CRUD + 搜索 + 按 source 查询 | `InMemoryStorage`（**仅内存占位，不持久化**） | 生产须宿主实现持久化（如 SQLite）；重启后数据依赖宿主实现 |
+| `IMemoryStorage` | 记忆 CRUD + 搜索 + 按 source 查询 | 内置内存默认实现（**仅内存占位，不持久化**；内部类，不挂公共面——PUB-API-PRUNE-2 收面）+ **可选落盘实现** `createNodeSqliteStorage(dbPath)`（基于 `node:*` 内建模块，零第三方依赖） | 持久化后端由宿主选：经内核工厂建 SQLite，或自实现（JSON / 自有 SQLite）；重启后数据依赖所选实现 |
 | `ISessionStore` | 会话历史 + 标题元数据持久化 | 无（宿主实现） | **不含检查点持久化**（2026-09-10 减法：跨重启恢复链整体退役）——中止/断电一律把未完成 turn 补全为完整 turn 身份、下次会话按历史加载；运行时暂停是同 turn 内续跑（内存态），无需跨进程载体 |
 | `ILogger` | 日志输出 | console fallback | 无 |
-| `ITracer` | 可观测性 span | `NOOP_TRACER` | 无 |
+| `ITracer` | 可观测性 span | 内核内部 Noop 实现（不挂公共面；不传 `tracer` 即零开销） | 无 |
+
+### 多项目与 Agent 边界（形态定案）
+
+**一个 Agent 绑定一个项目**——`projectPath` + 一套存储 + 一个会话域。多项目由**宿主**为每个项目各创建一个 Agent 实例；内核既不做跨项目切换，也不维护跨项目名单。
+
+| 维度 | 形态 |
+|------|------|
+| 一个项目（一个 Agent） | 可拥有 N 个会话（`switchSession` / `switchToSession` / `forkSession`），**同一时刻只跑一个** |
+| N 个项目（N 个 Agent 实例） | **并行**运行，各自独立的记忆库 / 会话 / 项目锁 |
+| 并行度 | **按项目计，不按会话计** |
+| 项目内多会话 | **共享同一个记忆库**（检索无会话过滤）⇒ 经验跨会话连续 |
+
+> **取舍（明写）**：本形态**不对标主流「一个会话 = 一个 Agent 实例」**。代价是**同一项目内不能并行跑两个会话**（主流可开两个终端各推各的任务）——已知并接受，登记 `MULTI-SESS-1`（观察，不修），仅当出现「同一仓库要并行两个任务」的真实需求时才重议。
+> **理由**：记忆库归**项目**所有，会话只是项目内的对话线程——把身份边界画在项目而非会话，才能让同一项目的经验跨会话连续。
+> 接入细节、数据落点与历史演进见 [接入指南](docs/memora-接入指南.md)「多项目怎么办」。
 
 ## 项目结构
 
@@ -224,8 +231,8 @@ src/
 │   ├── assembler.ts  # 组件组装器（纯工厂）
 │   ├── contextManager.ts / contextPreparer.ts / toolExecutor.ts / toolRunner.ts ···
 │   ├── seed/         # turn（prepare → act/difficulty → reflect，含多 turn 任务编排）
-│   └── managers/     # 16 个专职 Manager/服务类（memoryInspector / memoryGovernance / roundSummaryGenerator / sessionManager / sessionArchiver / archiveCoordinator / workProjection / textPolishManager / chatLockManager 等）
-├── memory/           # 记忆引擎（IMemoryStorage + InMemoryStorage + 纯关键词召回 / 融合排序 / 治理常量）
+│   └── managers/     # 专职 Manager/服务类（memoryInspector / roundSummaryGenerator / sessionManager / sessionArchiver / archiveCoordinator / workProjection / textPolishManager / chatLockManager 等）
+├── memory/           # 记忆引擎（IMemoryStorage + InMemoryStorage + 可选 SQLite 落盘实现 + 纯关键词召回 / 融合排序 / 治理常量）
 ├── role-pack/        # 角色包（manifest 解析 + validator + strategyResolver + 能力映射）
 ├── skill/            # 技能管理（全局池 + 角色包绑定，渐进披露 + skillScriptRunner）
 ├── llm/              # LLM 适配层（provider + openaiCompatible + factory）
@@ -255,15 +262,12 @@ src/
 
 | 指标 | 数值 |
 |------|------|
-| 源码 | 117 个生产文件（src/，零第三方运行时依赖） |
-| 测试 | 内核 + 宿主双套 vitest，根配置统一跑（100+ 文件） |
-| 测试通过 | 2700+ 通过 / 1 skip |
-| 语句覆盖 | 90.65% |
-| 分支覆盖 | 84.83% |
-| 函数覆盖 | 92.41% |
-| 行覆盖 | 91.79% |
+| 源码 | src/ 全量生产文件（零第三方运行时依赖；此处不登记个数——计数是时点快照） |
+| 测试 | 内核 + 宿主双套 vitest，根配置统一跑 |
+| 测试通过 | 全量通过（条数 / skipped 数以发版前 CI 实测为准——计数是时点快照，此处不落账） |
+| 测试覆盖率 | 语句 / 分支 / 函数 / 行覆盖率以 `npm run test:cov` 实测为准（此处不登记百分比——数值是时点快照） |
 | 运行时依赖 | **0** |
-| 架构决策记录 | 26 个 ADR |
+| 架构决策记录 | 仓库 `.trae/decisions/` 目录（索引见该目录下的 `README.md`；此处不登记条数——计数是时点快照，每次新增即过期） |
 
 ## 开发命令
 
@@ -278,6 +282,7 @@ npm run build        # 编译到 dist/
 ## 文档
 
 - [接入指南](docs/memora-接入指南.md) — 宿主项目开发者完整接入手册
+- [**从 4.x 升级到 5.0.0**](docs/memora-升级指南-4.x-到-5.0.0.md) — 删了哪些 API、每项怎么改（major 升级必读）
 - [API 参考](docs/memora-api-reference.md) — 公共 API 速查
 - [角色包开放键指南](docs/role-pack-开放键指南.md) — manifest.json 开放键使用指南（三层消费方 + 速查）
 - [配置示例](config.example.json) — LLM / 安全配置模板

package/config.example.json

@@ -22,14 +22,7 @@
         "supportsStructuredOutput": true
       }
     },
-    "active": "mimimo",
-    "background": {
-      "provider": "doubao",
-      "model": "doubao-pro",
-      "apiKey": "${MEMORA_BACKGROUND_API_KEY}",
-      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
-      "temperature": 0.5
-    }
+    "active": "mimimo"
   },
   "memory": {
     "dataDir": "~/.memora",