@zooique/memora 4.0.0 → 5.0.0

package/README.en.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 @@
 ## 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. **v4.0.0 (first major)**: 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).
+> **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,13 +260,10 @@ 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 | In-repo `.trae/decisions/` directory (see its `README.md` for the index; no count listed here — any count is a point-in-time snapshot) |
 
@@ -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
 
@@ -287,7 +294,7 @@ npm run build        # Compile to dist/
 |---|---|---|---|
 | 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 |