@zooique/memora 1.0.1 → 2.0.3

package/README.en.md

@@ -0,0 +1,272 @@
+# Memora
+
+> Universal Agent Memory Kernel — Local-first, Private, Domain-agnostic. Everything is Memory.
+
+[![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-90%25-brightgreen)](https://vitest.dev)
+[![Tests](https://img.shields.io/badge/tests-1715%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 is this?
+
+Memora is an **Agent memory infrastructure** — it gives your AI Agent persistent, cross-session long-term memory.
+
+It solves one core problem: **LLMs are stateless, but user tasks are continuous.**
+
+Memora builds continuous evolution on top of stateless inference: memory persistence, intelligent recall, natural decay, semantic deduplication, conflict detection — a complete memory lifecycle, all running locally. Your data never leaves your machine.
+
+## Design Philosophy
+
+> **Everything is Memory.**
+>
+> Persona is "I remember who I am." Rules are "I remember how to behave." Skills are "I remember how to do certain things." Conversation history is "I remember what we talked about."
+
+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).
+
+## Core Capabilities
+
+| Capability | Description |
+|-----------|-------------|
+| **Long-term Memory** | Cross-session, cross-topic memory persistence with intelligent recall |
+| **Dual-channel Recall** | Semantic vector search + keyword search, hybridMerge fusion ranking |
+| **Memory Governance L1-L4** | L1 semantic dedup → L2 timeliness eval → L3 conflict detection → L4 scheduled decay |
+| **Relation Graph** | contradicts / supports / follows / refines / caused — five relation types |
+| **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-dependency Kernel** | No third-party runtime dependencies; persistence injected by host via interfaces |
+| **Content Guardrails** | Regex rules + block/warn actions, bidirectional input/output checking |
+| **Observability** | ITracer interface + structured spans, plug into any APM |
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @zooique/memora
+```
+
+### Create an Agent
+
+```typescript
+import { Agent, createLlmProvider } from '@zooique/memora';
+
+// Host responsibility: create an LLM Provider
+// Works with any OpenAI Chat Completions-compatible service
+const provider = createLlmProvider({
+  provider: 'openaiCompatible',
+  apiKey: process.env.LLM_API_KEY!,
+  baseUrl: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat',
+});
+
+// Create Agent
+const agent = new Agent({
+  projectPath: '/path/to/project',
+  provider,
+  configDir: '/path/to/agent-config', // personas / rules / skills
+  dataDir: '.memora',                 // memory data directory
+});
+
+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 agent automatically recalls "loves TypeScript"
+const reply = await agent.chatSync('What language do I like?');
+// → Answers based on recalled memory
+```
+
+### Memory Management
+
+```typescript
+// Search memories (hybrid: semantic + keyword)
+const hits = await agent.memory.searchHybrid('TypeScript preference', { limit: 5 });
+
+// Governance: semantic deduplication
+const report = await agent.deduplicateMemories();
+console.log(`Deduplicated ${report.deduplicatedCount} memories`);
+
+// Governance: timeliness evaluation
+const timeliness = await agent.evaluateTimeliness();
+
+// Governance: conflict detection
+const conflicts = await agent.detectConflicts();
+
+// Manual decay trigger
+await agent.runMemoryDecayOnce();
+```
+
+### 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      │               │
+│  │  - Dual-channel recall (semantic+keyword)│               │
+│  │  - Governance L1-L4 (dedup/age/conflict) │               │
+│  │  - Persona matching / Skill matching     │               │
+│  │  - Tool registration / execution         │               │
+│  │  - Session archive / Insight extraction  │               │
+│  └──────────────────────────────────────────┘               │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Six 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 + decay | `InMemoryStorage` |
+| `IVectorStore` | Semantic vector index | `JsonVectorStore` |
+| `IMemoryRelationStore` | Memory relation graph | `InMemoryRelationStore` |
+| `ISessionStore` | Session history persistence | None (host implements) |
+| `ILogger` | Logging output | console fallback |
+| `ITracer` | Observability spans | `NOOP_TRACER` |
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Library exports (pure types + interfaces, no CLI)
+├── agent/            # Agent facade + AgentLoop execution engine
+│   ├── agent.ts      # Facade class (single entry point for hosts)
+│   ├── loop.ts       # Core loop (reason → tool call → reflection retry)
+│   ├── assembler.ts  # Component assembler (pure factory, stateless)
+│   ├── toolExecutor.ts    # Tool registration & execution
+│   ├── contextManager.ts  # Context window management (truncation + summary)
+│   ├── guardrail.ts       # Content guardrails (regex + block/warn)
+│   └── managers/          # 15 specialized Managers
+│       ├── archiveCoordinator.ts   # Archive coordination
+│       ├── memoryInspector.ts      # Memory read/write (CRUD + search + stats)
+│       ├── memoryGovernance.ts     # Governance unified facade (L1-L4)
+│       ├── dedupManager.ts         # L1 semantic deduplication
+│       ├── memoryDecayScheduler.ts # L4 scheduled decay + L2 timeliness
+│       ├── memoryAdvisor.ts        # L3 conflict detection + health diagnosis
+│       ├── insightExtractor.ts     # Conversation insight extraction
+│       ├── relationBuilder.ts      # Memory relation building (ADR-014)
+│       ├── sessionManager.ts       # Session management (fork/switch)
+│       ├── sessionArchiver.ts      # Session content archiving
+│       ├── configManager.ts        # Config management (hot-reload rules/skills)
+│       ├── autoConfigRefiner.ts    # Self-evolving config suggestions
+│       ├── workProjection.ts       # Work projection management
+│       ├── textPolishManager.ts    # Text polishing
+│       └── chatLockManager.ts      # Chat concurrency lock
+├── memory/           # Memory engine
+│   ├── types.ts          # Memory primitive (8 fields) + relation types
+│   ├── storageInterface.ts  # IMemoryStorage interface (16 methods)
+│   ├── recall.ts         # Dual-channel recall (semantic + keyword)
+│   ├── hybridMerge.ts    # Fusion ranking algorithm
+│   ├── vectorStore.ts    # IVectorStore + JsonVectorStore
+│   ├── relationStore.ts  # IMemoryRelationStore interface
+│   ├── governance.ts     # Governance shared constants (decay/boost/ceiling)
+│   ├── userProfile.ts    # User profile management
+│   └── projectManager.ts # Multi-project registry + lock management
+├── llm/              # LLM adapter layer
+│   ├── provider.ts       # LlmProvider abstract class
+│   ├── openaiCompatible.ts  # OpenAI-compatible protocol implementation
+│   ├── embedding.ts      # EmbeddingProvider (/embeddings endpoint)
+│   └── factory.ts        # createLlmProvider factory
+├── persona/          # Persona management (pure files + in-memory cache)
+├── skill/            # Skill management (keyword matching + per-turn injection)
+├── security/         # Security (two-level permissions + path whitelist + audit)
+├── config/           # Config loading (JSON + env variable interpolation)
+├── logging/          # Logging (ILogger interface + lazy initialization)
+├── eval/             # Eval framework (EvalScenario + EvalRunner, for CI)
+└── utils/            # Utilities (event emitter / segmenter / errors / timers)
+```
+
+## 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 | Open-string source primitive ("Everything is Memory" v2) | ADR-004 |
+| Vector Search | IVectorStore interface + built-in JsonVectorStore (pure JS cosine similarity) | ADR-002 |
+| Relation Graph | IMemoryRelationStore sidecar model (non-invasive to Memory primitive) | ADR-014 |
+| 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 | 82 files / 17,459 lines |
+| Tests | 75 files / 23,042 lines (test code > production code) |
+| Tests Passing | 1,715+ |
+| Statement Coverage | 89.3% |
+| Branch Coverage | 81.7% |
+| Function Coverage | 91.7% |
+| Runtime Dependencies | **0** |
+| Architecture Decision Records | 25 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 / Embedding / Security config template
+
+## Host Project
+
+[memora-sprite](hosts/memora-sprite/) — An Electron-based desktop sprite host (v1.5.0), demonstrating a complete Memora integration: SQLite persistence, vector indexing, system tray, global shortcuts, and memory graph visualization.
+
+## 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/decay/conflict) | ⚠️ 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 |
+
+## Contributing
+
+This project follows the "Big Tree Model" engineering philosophy. Architecture Decision Records (ADRs) are in `.trae/decisions/`.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,27 +1,49 @@
 # Memora
 
-> 通用 Agent 内核 — 本地、私有、领域无关，万物皆记忆
+> 通用 Agent 记忆内核 — 本地、私有、领域无关，万物皆记忆
 
 [![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-90%25-brightgreen)](https://vitest.dev)
+[![Tests](https://img.shields.io/badge/tests-1715%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)
 
+**English** → [README.en.md](./README.en.md)
+
+---
+
+## 这是什么？
+
+Memora 是一个 **Agent 记忆基础设施**——让你的 AI Agent 拥有跨会话、跨话题的长期记忆能力。
+
+它解决一个核心问题：**LLM 是无状态的，但用户的任务是连续的。**
+
+Memora 在无状态推理之上构建连续演化能力：记忆沉淀、智能召回、自然衰减、语义去重、冲突检测——完整的记忆生命周期管理，全部在本地完成，数据不出你的机器。
+
 ## 设计哲学
 
 > **万物皆是记忆。**
 >
-> 除了用户当前直接输入的提示词内容，Agent 的一切都是记忆——人格是"我记得我是谁"，规则是"我记得该怎么做事"，技能是"我记得怎么做某类事"，对话历史是"我记得之前聊过什么"。
+> 人格是"我记得我是谁"，规则是"我记得该怎么做事"，技能是"我记得怎么做某类事"，对话历史是"我记得之前聊过什么"。
 
 Memora 是一个**无法独立运行**的智能大脑内核——它只有接口，没有"形态"。CLI、WebUI、桌面精灵、小说生成器都是它的"宿主"，宿主负责给它身体（UI）、血管（Provider）、神经网络（事件回路）。
 
 ## 核心能力
 
-- **长期记忆沉淀**——跨会话、跨话题的记忆持久化与智能召回
-- **Agent 与角色分离**——Agent 是纯记忆引擎，角色是人格载体。换角色不丢记忆
-- **记忆统一模型**——角色、规则、技能、对话历史全部统一为「记忆」，通过 `source` 开放字符串区分
-- **领域可插拔**——同一套架构，加载不同记忆配置即可适配不同领域
-- **零依赖内核**——核心层仅依赖 `zod`，持久化由宿主通过接口注入
+| 能力 | 说明 |
+|------|------|
+| **长期记忆沉淀** | 跨会话、跨话题的记忆持久化与智能召回 |
+| **双通道召回** | 语义向量搜索 + 关键词搜索，hybridMerge 融合排序 |
+| **记忆治理 L1-L4** | L1 语义去重 → L2 时效评估 → L3 冲突检测 → L4 定时衰减 |
+| **记忆关系图谱** | contradicts / supports / follows / refines / caused 五种关系类型 |
+| **Agent 与角色分离** | Agent 是纯记忆引擎，角色是人格载体。换角色不丢记忆 |
+| **统一记忆模型** | 一切统一为「记忆」，通过 `source` 开放字符串区分，无封闭枚举 |
+| **领域可插拔** | 同一套架构，加载不同记忆配置即可适配不同领域 |
+| **零依赖内核** | 核心层无任何第三方运行时依赖，持久化由宿主通过接口注入 |
+| **内容护栏** | 正则规则 + block/warn 双动作，输入输出双向检查 |
+| **可观测性** | ITracer 接口 + 结构化 span，宿主可接入任意 APM |
 
 ## 快速开始
 
@@ -36,7 +58,7 @@ npm install @zooique/memora
 ```typescript
 import { Agent, createLlmProvider } from '@zooique/memora';
 
-// 宿主职责：创建 LLM Provider
+// 宿主职责：创建 LLM Provider（兼容所有 OpenAI Chat Completions 协议的服务）
 const provider = createLlmProvider({
   provider: 'openaiCompatible',
   apiKey: process.env.LLM_API_KEY!,
@@ -49,25 +71,44 @@ const agent = new Agent({
   projectPath: '/path/to/project',
   provider,
   configDir: '/path/to/agent-config', // personas / rules / skills
-  // dataDir 默认为 '~/.memora'，此处显式指定项目级目录
-  dataDir: '.memora',
+  dataDir: '.memora',                 // 记忆数据存储目录
 });
 
 await agent.init();
 ```
 
-### 对话
+### 对话（流式）
 
 ```typescript
-// 流式对话
-for await (const chunk of agent.chat('你好')) {
+for await (const chunk of agent.chat('你好，记住我喜欢 TypeScript')) {
   if (chunk.type === 'text') {
     process.stdout.write(chunk.content);
   }
 }
 
-// 同步对话（测试用）
-const reply = await agent.chatSync('你好');
+// 下一次对话，Agent 会自动召回"喜欢 TypeScript"这条记忆
+const reply = await agent.chatSync('我喜欢什么语言？');
+// → 基于召回的记忆回答
+```
+
+### 记忆管理
+
+```typescript
+// 搜索记忆
+const hits = await agent.memory.searchHybrid('TypeScript 偏好', { limit: 5 });
+
+// 记忆治理：语义去重
+const report = await agent.deduplicateMemories();
+console.log(`去重 ${report.deduplicatedCount} 条`);
+
+// 记忆治理：时效性评估
+const timeliness = await agent.evaluateTimeliness();
+
+// 记忆治理：冲突检测
+const conflicts = await agent.detectConflicts();
+
+// 手动触发衰减
+await agent.runMemoryDecayOnce();
 ```
 
 ### 关闭
@@ -89,41 +130,107 @@ await agent.close();
 │  ┌──────────────────────────────────────────┐               │
 │  │  Memora 内核（Agent）                    │               │
 │  │  - chat(input) → 流式响应                │               │
-│  │  - 记忆搜索 / 归档 / 挂载                │               │
-│  │  - 角色匹配 / 技能匹配                   │               │
-│  │  - 工具注册 / 工具执行                   │               │
+│  │  - 双通道记忆召回（语义 + 关键词）       │               │
+│  │  - 记忆治理 L1-L4（去重/时效/冲突/衰减） │               │
+│  │  - 角色匹配 / 技能匹配 / 护栏检查        │               │
+│  │  - 工具注册 / 工具执行 / 反思重试        │               │
+│  │  - 会话归档 / 洞察提取 / 关系构建        │               │
 │  └──────────────────────────────────────────┘               │
 └────────────────────────────────────────────────────────────┘
 ```
 
+### 六大注入接口
+
+内核通过接口与外部世界交互，宿主按需注入：
+
+| 接口 | 职责 | 内置实现 |
+|------|------|----------|
+| `IMemoryStorage` | 记忆 CRUD + 搜索 + 衰减 | `InMemoryStorage` |
+| `IVectorStore` | 语义向量索引 | `JsonVectorStore` |
+| `IMemoryRelationStore` | 记忆关系图谱 | `InMemoryRelationStore` |
+| `ISessionStore` | 会话历史持久化 | 无（宿主实现） |
+| `ILogger` | 日志输出 | console fallback |
+| `ITracer` | 可观测性 span | `NOOP_TRACER` |
+
 ## 项目结构
 
 ```
 src/
-├── index.ts        # 库导出入口（纯类型 + 接口导出，无 CLI）
-├── agent/          # Agent 门面 + AgentLoop + 工具执行 + managers/（9 个专职 Manager）
-├── memory/         # 记忆引擎（IMemoryStorage + IMemoryRelationStore + 召回 + 向量存储）
-├── persona/        # 角色管理
-├── skill/          # 技能管理
-├── llm/            # LLM 适配层
-├── security/       # 安全策略
-├── config/         # 配置加载
-├── logging/        # 日志
-├── eval/           # 评估框架（Mock Eval / Agent 行为回归测试）
-└── utils/          # 工具函数
+├── index.ts          # 库导出入口（纯类型 + 接口导出，无 CLI）
+├── agent/            # Agent 门面 + AgentLoop 执行引擎
+│   ├── agent.ts      # 门面类（宿主唯一入口）
+│   ├── loop.ts       # 核心循环（推理 → 工具调用 → 反思重试）
+│   ├── assembler.ts  # 组件组装器（纯工厂，不持有状态）
+│   ├── toolExecutor.ts    # 工具注册与执行
+│   ├── contextManager.ts  # 上下文窗口管理（截断 + 摘要）
+│   ├── guardrail.ts       # 内容护栏（正则 + block/warn）
+│   └── managers/          # 15 个专职 Manager
+│       ├── archiveCoordinator.ts   # 归档协调（会话归档 + 洞察提取）
+│       ├── memoryInspector.ts      # 记忆读写（CRUD + 搜索 + 统计）
+│       ├── memoryGovernance.ts     # 治理统一门面（L1-L4）
+│       ├── dedupManager.ts         # L1 语义去重
+│       ├── memoryDecayScheduler.ts # L4 定时衰减 + L2 时效评估
+│       ├── memoryAdvisor.ts        # L3 冲突检测 + 健康诊断
+│       ├── insightExtractor.ts     # 对话洞察提取
+│       ├── relationBuilder.ts      # 记忆关系构建（ADR-014）
+│       ├── sessionManager.ts       # 会话管理（分叉/切换）
+│       ├── sessionArchiver.ts      # 会话内容归档
+│       ├── configManager.ts        # 配置管理（规则/技能热加载）
+│       ├── autoConfigRefiner.ts    # 自进化配置建议
+│       ├── workProjection.ts       # 作品投影管理
+│       ├── textPolishManager.ts    # 文本润色
+│       └── chatLockManager.ts      # 对话并发锁
+├── memory/           # 记忆引擎
+│   ├── types.ts          # Memory 基元（8 字段）+ 关系类型
+│   ├── storageInterface.ts  # IMemoryStorage 接口（16 方法）
+│   ├── recall.ts         # 双通道召回（语义 + 关键词）
+│   ├── hybridMerge.ts    # 融合排序算法
+│   ├── vectorStore.ts    # IVectorStore + JsonVectorStore
+│   ├── relationStore.ts  # IMemoryRelationStore 接口
+│   ├── governance.ts     # 治理共享常量（衰减/提升/上限）
+│   ├── userProfile.ts    # 用户画像管理
+│   └── projectManager.ts # 多项目注册 + 锁管理
+├── llm/              # LLM 适配层
+│   ├── provider.ts       # LlmProvider 抽象类
+│   ├── openaiCompatible.ts  # OpenAI 兼容协议实现
+│   ├── embedding.ts      # EmbeddingProvider（/embeddings 端点）
+│   └── factory.ts        # createLlmProvider 工厂
+├── persona/          # 角色管理（纯文件 + 内存缓存）
+├── skill/            # 技能管理（关键词匹配 + 当轮注入）
+├── security/         # 安全策略（两级权限 + 路径白名单 + 审计）
+├── config/           # 配置加载（JSON + 环境变量插值）
+├── logging/          # 日志（ILogger 接口 + 懒初始化）
+├── eval/             # 评估框架（EvalScenario + EvalRunner，CI 用）
+└── utils/            # 工具函数（事件系统/分词/分片/错误/定时器）
 ```
 
 ## 技术栈
 
-| 类别 | 选型 | 决策 |
-|------|------|------|
+| 类别 | 选型 | 决策依据 |
+|------|------|----------|
 | 运行时 | Node.js ≥ 22 LTS + TypeScript 5 strict + ESM | ADR-001 |
 | 数据层 | IMemoryStorage 接口（宿主注入持久化实现） | ADR-002 |
-| LLM | OpenAI Chat Completions 兼容协议 | ADR-003 |
-| 形态 | 纯逻辑库（CLI 由宿主提供） | ADR-002 |
-| 安全 | 两级权限 + 路径白名单 | ADR-006 |
+| LLM 协议 | OpenAI Chat Completions 兼容（流式 SSE + Tool Calling） | ADR-003 |
+| 记忆模型 | source 开放字符串基元驱动（万物皆记忆 v2） | ADR-004 |
+| 向量检索 | IVectorStore 接口 + 内置 JsonVectorStore（纯 JS 余弦相似度） | ADR-002 |
+| 关系图谱 | IMemoryRelationStore 侧车模型（不侵入 Memory 基元） | ADR-014 |
+| 形态 | 纯逻辑库（零 native 依赖，CLI/UI 由宿主提供） | ADR-002 |
+| 安全 | 两级权限 + 路径白名单 + 审计日志 | ADR-006 |
 | 测试 | Vitest + MSW Mock LLM + InMemoryStorage | ADR-007 |
 
+## 工程质量
+
+| 指标 | 数值 |
+|------|------|
+| 源码 | 82 文件 / 19,060 行 |
+| 测试 | 75 文件 / 23,748 行（测试代码量 > 生产代码量） |
+| 测试通过 | 1,716+ |
+| 语句覆盖 | 89.3% |
+| 分支覆盖 | 81.7% |
+| 函数覆盖 | 91.7% |
+| 运行时依赖 | **0** |
+| 架构决策记录 | 25 个 ADR |
+
 ## 开发命令
 
 ```bash
@@ -131,18 +238,23 @@ npm test             # 运行测试
 npm run test:cov     # 运行测试 + 覆盖率
 npm run typecheck    # TypeScript 类型检查
 npm run lint         # ESLint 检查
+npm run build        # 编译到 dist/
 ```
 
 ## 文档
 
-详细接入指南与 API 参考文档随源码提供。本包核心使用方式见上文「快速开始」。
+- [接入指南](docs/memora-接入指南.md) — 宿主项目开发者完整接入手册
+- [API 参考](docs/memora-api-reference.md) — 公共 API 速查
+- [配置示例](config.example.json) — LLM / Embedding / 安全配置模板
+
+## 宿主项目
 
-技术决策记录（ADR）目前为内部文档，不随 npm 包分发。
+[memora-sprite](hosts/memora-sprite/) — 基于 Electron 的桌面精灵宿主（v1.5.0），展示 Memora 内核的完整接入方式：SQLite 持久化、向量索引、系统托盘、全局快捷键、记忆图谱可视化。
 
 ## 贡献
 
-本项目遵循"大树模型"工程哲学。
+本项目遵循"大树模型"工程哲学。技术决策记录（ADR）位于 `.trae/decisions/`。
 
 ## 许可证
 
-MIT
+[MIT](LICENSE)