@zooique/memora 2.0.0 → 3.0.0

package/README.en.md

@@ -0,0 +1,305 @@
+# Memora
+
+> **Agent Memory Kernel with Governance** — Local-first, Private, Zero-dep. Not a framework, a kernel.
+
+[![npm](https://img.shields.io/npm/v/@zooique/memora)](https://www.npmjs.com/package/@zooique/memora)
+[![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)
+[![Dependencies](https://img.shields.io/badge/runtime%20deps-0-yellowgreen)](package.json)
+[![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+**中文** → [README.md](./README.md)
+
+---
+
+## 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
+- **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
+
+## How Memora solves this
+
+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.
+
+```typescript
+import { Agent, createProviderFromConfig } from '@zooique/memora';
+
+const agent = new Agent({
+  projectPath: '/your/project',
+  dataDir: '/your/project/.memora-data', // memory data directory (required)
+  provider: createProviderFromConfig('primary', {
+    provider: 'openaiCompatible',
+    apiKey: process.env.LLM_API_KEY!,
+    baseUrl: 'https://api.openai.com/v1',
+    model: 'gpt-4o',
+  }),
+});
+await agent.init();
+
+// Chat — memories persist automatically
+for await (const chunk of agent.chat('I love TypeScript')) {
+  process.stdout.write(chunk.content);
+}
+
+// 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();
+```
+
+> **Boundary**: Memora is a **non-standalone pure logic kernel** — persistence, sandbox, observability, CLI/UI are all injected by the host. The kernel guarantees **interface contracts + unit-tested logic correctness**; agent-level behavior evaluation is the host's responsibility.
+
+---
+
+## Why Memora?
+
+| | Memora | Vector memory libs (agent-memory, MemStack) | Framework-builtin memory (Mastra, LangGraph) |
+|---|---|---|---|
+| **Memory governance** | ✅ Dedup+conflict+write-time supersede | ⚠️ 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.
+
+---
+
+## Design Philosophy
+
+> **Memory-as-Summary.**
+>
+> Conversation is the raw material: after each turn, an asynchronous round-summary is generated as the sole memory unit; the original conversation records are stored separately and traceable via source links. Persona, rules, and skills live in the role-pack, not the memory store.
+
+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.
+
+---
+
+## Core Capabilities
+
+| Capability | Description |
+|-----------|-------------|
+| **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) |
+| **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 |
+| **Zero third-party runtime deps** | Depends on Node built-ins (`node:*`); persistence injected by host via interfaces |
+| **Observability** | ITracer interface + structured spans, plug into any APM |
+| **External tools** | Conditionally exposed `web_search` / `web_fetch` / `run_code` — enabled only when host injects the corresponding provider |
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @zooique/memora
+```
+
+### Create an Agent
+
+```typescript
+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.
+const provider = createProviderFromConfig('primary', {
+  provider: 'openaiCompatible',
+  apiKey: process.env.LLM_API_KEY!,
+  baseUrl: 'https://api.xiaomimimo.com/v1',
+  model: 'deepseek-chat',
+});
+
+// Create Agent
+const agent = new Agent({
+  projectPath: '/path/to/project',
+  provider,
+  configDir: '/path/to/agent-config', // role-packs / skills
+  dataDir: '/path/to/project/.memora-data', // memory data directory (required; prefer absolute)
+});
+
+await agent.init();
+```
+
+### Chat (Streaming)
+
+```typescript
+for await (const chunk of agent.chat('Hi, remember that I love TypeScript')) {
+  if (chunk.type === 'text') {
+    process.stdout.write(chunk.content);
+  }
+}
+
+// Next session — the LLM can call search_memories to retrieve "loves TypeScript"
+const reply = await agent.chatSync('What language do I like?');
+// → Answers based on the memories the LLM retrieved
+```
+
+### Memory Management
+
+```typescript
+// 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): per-source count / days since last access (score retired → factual observation only)
+const health = agent.governance.sourceHealth();
+console.log(health?.sources);
+```
+
+### Cleanup
+
+```typescript
+await agent.close();
+```
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Host Application (CLI / Desktop Sprite / WebUI / Game)    │
+│  ┌─────────────────┐    ┌──────────────────┐               │
+│  │ LLM Provider     │◄───│ API Key / baseUrl │  ← Host job  │
+│  └────────┬────────┘    └──────────────────┘               │
+│           │ inject                                          │
+│           ▼                                                 │
+│  ┌──────────────────────────────────────────┐               │
+│  │  Memora Kernel (Agent)                   │               │
+│  │  - chat(input) → streaming response      │               │
+│  │  - Keyword-only search (semantic vector channel removed via B0)│               │
+│  │  - Memory governance (dedup/conflict/supersede) │         │
+│  │  - Role pack matching / Skill matching   │               │
+│  │  - Tool registration / execution         │               │
+│  │  - Session archive / round persistence   │               │
+│  └──────────────────────────────────────────┘               │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Five Injectable Interfaces
+
+The kernel interacts with the outside world through interfaces. Hosts inject implementations as needed:
+
+| Interface | Responsibility | Built-in Implementation |
+|-----------|---------------|------------------------|
+| `IMemoryStorage` | Memory CRUD + search + query by source | `InMemoryStorage` |
+| `ISessionStore` | Session history persistence | None (host implements) |
+| `ILogger` | Logging output | console fallback |
+| `ITracer` | Observability spans | `NOOP_TRACER` |
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Library exports (types + interfaces + functions + classes, no CLI)
+├── agent/            # Agent facade + AgentLoop + seed/ (single-turn execution loop)
+│   ├── agent.ts      # Facade class (single entry point for hosts)
+│   ├── loop.ts       # Core loop (reason → tool call → reflection retry)
+│   ├── 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)
+├── 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)
+├── security/         # Security (path guard / write confirmation)
+├── config/           # Config loading
+├── code-exec/        # Generic code execution abstraction (conditionally exposed)
+├── web-search/       # Web search abstraction (conditionally exposed)
+├── web-fetch/        # Web fetch abstraction (conditionally exposed)
+├── logging/          # Logging (ILogger interface + console fallback)
+└── utils/            # Utilities (scanner / segmenter / event system / atomic write)
+```
+
+## Tech Stack
+
+| Category | Choice | Rationale |
+|----------|--------|-----------|
+| Runtime | Node.js ≥ 22 LTS + TypeScript 5 strict + ESM | ADR-001 |
+| Data Layer | IMemoryStorage interface (host injects persistence) | ADR-002 |
+| LLM Protocol | OpenAI Chat Completions compatible (streaming SSE + Tool Calling) | ADR-003 |
+| Memory Model | Memory-as-summary: round-summary single track, traceable to source; source open-string primitive | ADR-004 · memory-as-summary.md |
+| Conflict Resolution | Memory conflicts resolved via supersededBy boolean flag | ADR-021 |
+| Form Factor | Pure logic library (zero native deps, CLI/UI provided by host) | ADR-002 |
+| Security | Two-level permissions + path whitelist + audit log | ADR-006 |
+| Testing | Vitest + MSW Mock LLM + InMemoryStorage | ADR-007 |
+
+## Engineering Quality
+
+| 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% |
+| Runtime Dependencies | **0** |
+| Architecture Decision Records | 26 ADRs |
+
+## Development
+
+```bash
+npm test             # Run tests
+npm run test:cov     # Run tests + coverage
+npm run typecheck    # TypeScript type checking
+npm run lint         # ESLint
+npm run build        # Compile to dist/
+```
+
+## Documentation
+
+- [Integration Guide](docs/memora-接入指南.md) — Complete host developer onboarding manual (Chinese)
+- [API Reference](docs/memora-api-reference.md) — Public API quick reference (Chinese)
+- [Config Example](config.example.json) — LLM / Security config template
+
+## Host Project
+
+[memora-vscode](https://gitee.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?
+
+| | 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 |
+| 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 |
+
+## Feedback
+
+Found a bug or have a suggestion? Please open an issue at [Gitee Issues](https://gitee.com/zooique/memora/issues) (primary repository) or [GitHub Issues](https://github.com/zooique/memora/issues) (mirror).
+
+## Contributing
+
+This project follows the "Big Tree Model" engineering philosophy. Architecture Decision Records (ADRs) are in the repository [.trae/decisions/](https://gitee.com/zooique/memora/tree/main/.trae/decisions).
+
+## License
+
+[MIT](LICENSE)