memory-forge 0.1.9 → 0.2.1

package/README.md

@@ -1,93 +1,76 @@
 # MemoryForge
 
-> AI Agent 持久记忆引擎。8 个 MCP 工具 + 5 个自动化引擎。Free 层本地运行，Pro 层 Shelby 去中心化云同步。
+> Persistent memory engine for AI agents. 8 MCP tools + 5 auto-engines. Free tier runs locally, Pro tier adds Shelby decentralized cloud sync.
 
-## 安装
+## Install
 
 ```bash
 npx memory-forge setup
 ```
 
-自动配置 Claude Code hooks（SessionStart / Stop / PreCompact），导入已有规则为记忆。
+Auto-configures Claude Code hooks (SessionStart / Stop / PreCompact) and imports existing rules as memories.
 
-Free 层零依赖外部服务。Pro 层需 `SHELBY_API_KEY` 启用 Shelby 云同步。
+Free tier has no external service dependencies. Pro tier requires a `SHELBY_API_KEY` for Shelby cloud sync.
 
-## 核心能力
+## Core Capabilities
 
-**8 个 MCP 工具（Agent 直接调用）：**
+**8 MCP Tools (invoked by agent directly):**
 
-| 工具 | 说明 |
+| Tool | Description |
 |---|---|
-| `memory_store` | 存储记忆，自动向量化 + 命名 + 去重合并 |
-| `memory_search` | 语义检索（向量 + 关键词双模式） |
-| `memory_recall` | 按 ID 精确获取 |
-| `memory_list` | 列出记忆，支持分类 / 标签过滤 |
-| `memory_forget` | 删除记忆（本地 + Shelby 同步） |
-| `memory_context` | 加载当前会话上下文 |
-| `memory_export` | 导出 JSON 或 Markdown |
-| `memory_share` | 打包记忆供队友导入 |
-
-**5 个自动化引擎（用户无感知）：**
-
-| 引擎 | 说明 |
+| `memory_store` | Store memories with auto-embedding, naming, and dedup merge |
+| `memory_search` | Semantic search (vector + keyword dual-mode) |
+| `memory_recall` | Exact recall by memory ID |
+| `memory_list` | List memories with category/tag filtering |
+| `memory_forget` | Delete a memory (local + Shelby tombstone) |
+| `memory_context` | Load current session context |
+| `memory_export` | Export as JSON or Markdown |
+| `memory_share` | Package a memory for teammate import |
+
+**5 Auto-Engines (zero user awareness):**
+
+| Engine | Description |
 |---|---|
-| autoName | 从内容自动提取记忆名称 |
-| autoMerge | 检测 >80% 重叠自动合并 |
-| autoPriority | 基于访问频率 + 时效计算优先级（Ebbinghaus 遗忘曲线） |
-| autoDecay | 90 天未访问自动归档 |
-| autoCapture | 会话结束自动更新优先级 + 清理过期；PreCompact 提醒 Agent 保存关键信息 |
+| autoName | Extract name from content automatically |
+| autoMerge | Detect >80% overlap and merge duplicates |
+| autoPriority | Priority scoring via access frequency + recency (Ebbinghaus curve) |
+| autoDecay | Auto-archive at 90 days of inactivity |
+| autoCapture | Session-end priority recalc + PreCompact save reminders |
 
-## 定价
+## Pricing
 
-| 方案 | 说明 |
+| Tier | Description |
 |---|---|
-| **Free** | 8 工具，本地存储，无限制记忆 |
-| **Pro** | + Shelby 去中心化云同步，多设备 |
+| **Free** | 8 tools, local storage, unlimited memories |
+| **Pro** | + Shelby decentralized cloud sync, cross-device |
 
-Pro 当前在测试网阶段。
+Pro is currently on Shelbynet testnet.
 
-## 技术栈
+## Tech Stack
 
-- **MCP 协议**: `@modelcontextprotocol/sdk` (stdio transport)
-- **嵌入模型**: Transformers.js / Xenova all-MiniLM-L6-v2（23MB，本地运行，失败自动降级关键词搜索）
-- **云存储 (Pro)**: `@shelby-protocol/sdk` (Shelbynet / Aptos)
-- **运行时**: Node.js 18+, TypeScript
+- **MCP Protocol**: `@modelcontextprotocol/sdk` (stdio transport)
+- **Embeddings**: Transformers.js / Xenova all-MiniLM-L6-v2 (23MB, local, auto-fallback to keyword)
+- **Cloud (Pro)**: `@shelby-protocol/sdk` (Shelbynet / Aptos)
+- **Runtime**: Node.js 18+, TypeScript
 
-## 项目结构
+## Docs
 
-```
-agentvault/
-├── README.md
-├── package.json
-├── server.json          # MCP Registry manifest
-├── Dockerfile
-├── smithery.yaml
-├── tsconfig.json
-└── src/
-    ├── index.ts         # MCP Server 入口 + CLI 路由
-    ├── store.ts         # MemoryStore: LRU 缓存 + 向量/关键词搜索
-    ├── embedding.ts     # Transformers.js 嵌入引擎
-    ├── setup.ts         # 一键安装流程
-    ├── pro.ts           # Pro 激活 + Shelby 云同步
-    ├── auto/
-    │   └── index.ts     # 5 个自动化引擎
-    ├── storage/
-    │   ├── local.ts     # 本地 Markdown 存储
-    │   └── shelby.ts    # Shelby 云存储
-    ├── hooks/
-    │   └── install.ts   # Claude Code hooks 配置
-    └── migrate/
-        └── import.ts    # 规则导入 + 去重
-```
+| Document | Content |
+|---|---|
+| [TECHNICAL.md](TECHNICAL.md) | API reference, data model, architecture, security |
+| [TUTORIAL.md](TUTORIAL.md) | Install guide, daily use, Pro setup, troubleshooting |
+| [SPEC.md](SPEC.md) | Product specification and roadmap |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture and data flow |
+| [MARKET.md](MARKET.md) | Competitive analysis |
 
-## 安全
+## Security
 
-- Free 层全本地，零网络请求（除首次模型下载 23MB）
-- Pro 层记忆上传至 Shelby 链上存储，每条有 Aptos 交易证明
-- API key 通过环境变量注入，不存储密钥明文
-- 支持 GDPR 被遗忘权（`memory_forget` 删除本地 + 链上 tombstone）
+- Free tier is fully local — zero network requests (except one-time 23MB model download)
+- Pro tier uploads to Shelby blockchain storage with Aptos transaction proofs
+- API key via environment variable; secrets never stored in plaintext
+- GDPR right-to-erasure via `memory_forget` (local + on-chain tombstone)
 
-## 测试
+## Tests
 
 ```bash
 npm test   # 48 tests, 100% pass

package/TECHNICAL.md

@@ -1,40 +1,40 @@
-# MemoryForge 技术文档
+# MemoryForge — Technical Documentation
 
-> 版本 0.1.8 | 8 MCP 工具 + 5 自动引擎 | Free 本地 + Pro Shelby 云
+> Version 0.2.0 | 8 MCP Tools + 5 Auto-Engines | Free (local) + Pro (Shelby cloud)
 
-## 目录
+## Table of Contents
 
-1. [系统架构](#系统架构)
-2. [数据模型](#数据模型)
-3. [MCP 工具 API 参考](#mcp-工具-api-参考)
-4. [自动引擎](#自动引擎)
-5. [Hook 系统](#hook-系统)
-6. [存储层](#存储层)
-7. [嵌入引擎](#嵌入引擎)
-8. [安全模型](#安全模型)
-9. [Pro 层 (Shelby 云)](#pro-层-shelby-云)
-10. [错误处理与降级](#错误处理与降级)
+1. [System Architecture](#system-architecture)
+2. [Data Model](#data-model)
+3. [MCP Tool API Reference](#mcp-tool-api-reference)
+4. [Auto-Engines](#auto-engines)
+5. [Hook System](#hook-system)
+6. [Storage Layer](#storage-layer)
+7. [Embedding Engine](#embedding-engine)
+8. [Security Model](#security-model)
+9. [Pro Tier (Shelby Cloud)](#pro-tier-shelby-cloud)
+10. [Error Handling & Degradation](#error-handling--degradation)
 
 ---
 
-## 系统架构
+## System Architecture
 
 ```
 ┌─────────────────────────────────────┐
-│  AI Agent (Claude Code / Cursor)    │  MCP stdio 协议
+│  AI Agent (Claude Code / Cursor)    │  MCP stdio protocol
 ├─────────────────────────────────────┤
-│  CLI 路由 (index.ts)                │
+│  CLI Router (index.ts)              │
 │  setup / pro / hook / MCP Server    │
 ├─────────────────────────────────────┤
 │  8 MCP Tools                        │
 │  store / search / recall / list     │
 │  forget / context / export / share  │
 ├──────────────┬──────────────────────┤
-│  Free 层     │  Pro 层               │
-│  memoryStore │  ShelbyNodeClient     │
+│  Free Tier   │  Pro Tier             │
+│  MemoryStore │  ShelbyNodeClient     │
 │  local .md   │  upload/download/list │
 ├──────────────┴──────────────────────┤
-│  5 Auto Engines                     │
+│  5 Auto-Engines                     │
 │  name → merge → priority → decay    │
 │  → contextSummary                   │
 ├─────────────────────────────────────┤
@@ -45,47 +45,47 @@
 └─────────────────────────────────────┘
 ```
 
-### 源文件结构
+### Source File Structure
 
 ```
 agentvault/src/
-├── index.ts           # 入口: CLI 路由 + MCP Server
-├── store.ts           # MemoryStore: 内存索引 + 搜索
-├── embedding.ts       # Transformers.js 延迟加载引擎
-├── setup.ts           # 一键安装流程
-├── pro.ts             # Pro 激活 + 同步
-├── auto/index.ts      # 5 自动引擎
+├── index.ts           # Entry: CLI routing + MCP Server
+├── store.ts           # MemoryStore: in-memory index + search
+├── embedding.ts       # Transformers.js lazy-load engine
+├── setup.ts           # One-command install flow
+├── pro.ts             # Pro activation + bidirectional sync
+├── auto/index.ts      # 5 auto-engines
 ├── storage/
-│   ├── local.ts       # Markdown 文件读写
-│   └── shelby.ts      # Shelby 云 API 封装
-├── hooks/install.ts   # Claude Code hooks 配置
-└── migrate/import.ts  # 规则导入 + 去重
+│   ├── local.ts       # Markdown file read/write
+│   └── shelby.ts      # Shelby cloud API wrapper
+├── hooks/install.ts   # Claude Code hooks configuration
+└── migrate/import.ts  # Rule import + dedup
 ```
 
 ---
 
-## 数据模型
+## Data Model
 
-### Memory 接口
+### Memory Interface
 
 ```typescript
 interface Memory {
   id: string;              // UUID v4
-  name: string;            // 人类可读名称 (autoName 生成, 最长40字符)
-  content: string;         // 原始内容
-  category: string;        // 分类: user-preference | project-context | decision-log | code-pattern
-  tags: string[];          // 标签列表
-  priority: number;        // 1-10, autoPriority 动态调整
-  vector: number[];        // 384-dim 嵌入向量
-  created_at: string;      // ISO-8601 创建时间
-  access_count: number;    // 访问次数 (touch)
-  last_accessed: string | null;  // 最后访问时间
+  name: string;            // Human-readable name (autoName, max 40 chars)
+  content: string;         // Raw content
+  category: string;        // user-preference | project-context | decision-log | code-pattern
+  tags: string[];          // Tag list
+  priority: number;        // 1–10, dynamically adjusted by autoPriority
+  vector: number[];        // 384-dim embedding vector
+  created_at: string;      // ISO-8601 creation timestamp
+  access_count: number;    // Touch count
+  last_accessed: string | null;  // Last access timestamp
 }
 ```
 
-### 本地存储格式
+### Local Storage Format
 
-文件路径: `~/.memory-forge/memories/{id}.md`
+Path: `~/.memory-forge/memories/{id}.md`
 
 ```markdown
 # Memory Name
@@ -99,22 +99,22 @@ interface Memory {
 User prefers camelCase naming, single quotes, and 2-space indent.
 ```
 
-### MemoryStore 索引
+### MemoryStore Index
 
-- `Map<string, Memory>` 主存储
-- `Map<string, Float32Array>` 向量缓存
-- LRU 淘汰: 5000 条上限, 超出淘汰最低访问量×优先级
-- 去重: Jaccard 相似度 > 0.8 自动合并
+- `Map<string, Memory>` primary store
+- `Map<string, Float32Array>` vector cache
+- LRU eviction: 5,000 entry cap, evicts lowest `access_count × priority`
+- Dedup: Jaccard similarity > 0.8 triggers auto-merge
 
 ---
 
-## MCP 工具 API 参考
+## MCP Tool API Reference
 
-所有工具通过 MCP stdio 协议调用。Agent 自动获得，无需手动调用。
+All tools are invoked via the MCP stdio protocol. The agent receives them automatically — no manual invocation required.
 
 ### memory_store
 
-存储一条记忆。自动向量化、命名、去重合并。
+Store a memory. Auto-embeds, names, and dedup-merges.
 
 ```typescript
 // Input
@@ -122,37 +122,37 @@ User prefers camelCase naming, single quotes, and 2-space indent.
   content: string;        // required, min 1 char
   category?: string;      // "general" | "user-preference" | "project-context" | "decision-log" | "code-pattern"
   tags?: string[];        // default: []
-  priority?: number;      // 1-10, default: 5
+  priority?: number;      // 1–10, default: 5
 }
 
 // Output (success)
 {
   success: true;
-  merged?: boolean;       // true if merged with existing memory (>80% overlap)
+  merged?: boolean;       // true if merged with existing (>80% overlap)
   memory_id: string;
   name: string;
   preview: string;        // first 200 chars
 }
 ```
 
-**内部流程:**
-1. `embed(content)` → 384-dim vector (失败则 vector=[])
-2. `autoName(content)` → 从内容提取名称
-3. `autoMerge(store, memory)` → 检查已有记忆, >0.8 Jaccard 则合并
-4. `saveMemory(memory)` → 写本地 Markdown
-5. `store.add(memory)` → 更新 LRU 缓存
-6. Pro: `uploadMemory(memory)` → Shelby 云 (async, fire-and-forget)
+**Internal pipeline:**
+1. `embed(content)` → 384-dim vector (null on failure)
+2. `autoName(content)` → extract name from content
+3. `autoMerge(store, memory)` → check existing, merge if Jaccard > 0.8
+4. `saveMemory(memory)` → write local Markdown
+5. `store.add(memory)` → update LRU cache
+6. Pro: `uploadMemory(memory)` → Shelby cloud (async, fire-and-forget)
 
 ### memory_search
 
-语义检索记忆。向量优先, 失败自动降级关键词。
+Semantic memory search. Vector-first, auto-fallback to keyword.
 
 ```typescript
 // Input
 {
-  query: string;           // required, 自然语言
-  limit?: number;          // 1-20, default: 5
-  min_similarity?: number; // 0-1, default: 0.6
+  query: string;           // required, natural language
+  limit?: number;          // 1–20, default: 5
+  min_similarity?: number; // 0–1, default: 0.6
   category?: string;       // filter by category
   tags?: string[];         // filter by tags (OR match)
 }
@@ -172,21 +172,21 @@ User prefers camelCase naming, single quotes, and 2-space indent.
 }
 ```
 
-**评分公式 (向量模式):**
+**Scoring formula (vector mode):**
 ```
 score = cosineSimilarity(queryVec, memoryVec)
       × (priority / 5)
       × (1 + min(access_count, 10) × 0.05)
 ```
 
-**评分公式 (关键词模式):**
+**Scoring formula (keyword mode):**
 ```
 score = (contentHits × 2 + nameHits × 3) + priority
 ```
 
 ### memory_recall
 
-按 ID 精确获取一条记忆。
+Exact retrieval by memory ID.
 
 ```typescript
 // Input
@@ -204,21 +204,21 @@ score = (contentHits × 2 + nameHits × 3) + priority
 
 ### memory_list
 
-列出记忆目录，支持分页和过滤。
+List memories with pagination and filtering.
 
 ```typescript
 // Input
 {
   category?: string;    // filter
   tags?: string[];      // filter (OR match)
-  limit?: number;       // 1-100, default: 20
+  limit?: number;       // 1–100, default: 20
   offset?: number;      // default: 0
 }
 
 // Output
 {
-  total: number;        // 总记忆数
-  count: number;        // 当前页数量
+  total: number;        // total memory count
+  count: number;        // current page count
   memories: [{
     memory_id, name, category,
     tags, priority,
@@ -229,7 +229,7 @@ score = (contentHits × 2 + nameHits × 3) + priority
 
 ### memory_forget
 
-删除一条记忆（本地文件 + 内存缓存）。
+Delete a memory (local file + in-memory cache).
 
 ```typescript
 // Input
@@ -245,30 +245,30 @@ score = (contentHits × 2 + nameHits × 3) + priority
 
 ### memory_context
 
-加载当前会话上下文，返回最近访问的高优先级记忆摘要。
+Load current session context — returns top recently-accessed, high-priority memory summaries.
 
 ```typescript
 // Input
-{ limit?: number;  // 1-20, default: 5 }
+{ limit?: number;  // 1–20, default: 5 }
 
 // Output
 {
   context_loaded: true;
   memory_count: number;
-  context: string;  // 格式: "- [name] preview..."
+  context: string;  // format: "- [name] preview..."
 }
 ```
 
-**排序:** `access_count` DESC, 同分则 `priority` DESC。
+**Sort order:** `access_count` DESC, ties broken by `priority` DESC.
 
 ### memory_export
 
-导出记忆为 JSON 或 Markdown。
+Export memories as JSON or Markdown.
 
 ```typescript
 // Input
 {
-  memory_ids?: string[];  // 不指定则导出全部
+  memory_ids?: string[];  // omit to export all
   format?: "json" | "markdown";  // default: "json"
 }
 
@@ -289,7 +289,7 @@ score = (contentHits × 2 + nameHits × 3) + priority
 
 ### memory_share
 
-打包单条记忆供队友导入。
+Package a single memory for import by teammates.
 
 ```typescript
 // Input
@@ -313,78 +313,78 @@ score = (contentHits × 2 + nameHits × 3) + priority
 
 ---
 
-## 自动引擎
+## Auto-Engines
 
-所有引擎位于 `src/auto/index.ts`。
+All engines are located in `src/auto/index.ts`.
 
 ### autoName
 
-从内容提取人类可读名称。
+Extracts a human-readable name from content.
 
 ```
-算法:
-1. 移除代码块 (```...```)
-2. 取前 40 字符
-3. 换行替换为空格
-4. 空内容 → "memory"
+Algorithm:
+1. Strip code blocks (```...```)
+2. Take first 40 chars
+3. Replace newlines with spaces
+4. Empty content → "memory"
 ```
 
 ### autoMerge
 
-检测并合并重复记忆。
+Detects and merges duplicate memories.
 
 ```
-算法:
-1. Jaccard 相似度: |setA ∩ setB| / min(|setA|, |setB|)
-2. 单词长度 ≥ 3
-3. 阈值: > 0.8 → 合并
-4. 合并后重新计算向量
+Algorithm:
+1. Jaccard similarity: |setA ∩ setB| / min(|setA|, |setB|)
+2. Minimum word length: 3 chars
+3. Threshold: > 0.8 → merge
+4. Recompute embedding vector after merge
 ```
 
 ### autoPriority
 
-基于 Ebbinghaus 遗忘曲线计算优先级 (1-10)。
+Computes priority score (1–10) based on the Ebbinghaus forgetting curve.
 
 ```
-公式:
-freqWeight   = min(access_count, 50) / 50
-recencyWeight = 1 - (daysSinceLastAccess / 90)  // clamp 0-1
-ageWeight    = 1 - min(ageDays, 365) / 365
+Formula:
+freqWeight    = min(access_count, 50) / 50
+recencyWeight = 1 - (daysSinceLastAccess / 90)  // clamp 0–1
+ageWeight     = 1 - min(ageDays, 365) / 365
 
 priority = 1 + 9 × (freqWeight × 0.4 + recencyWeight × 0.4 + ageWeight × 0.2)
 ```
 
 ### autoDecay
 
-Ebbinghaus 遗忘曲线判定记忆是否归档。
+Determines whether a memory should be archived.
 
 ```
-| 天数 | 衰减值 | 含义 |
-|------|--------|------|
-| ≤1   | 1.0    | 活跃 |
-| ≤7   | 0.8    | 近期 |
-| ≤30  | 0.5    | 衰减中 |
-| ≤90  | 0.2    | 弱记忆 |
-| >90  | 0      | 归档 (删除) |
+| Days     | Decay Value | Status            |
+|----------|-------------|-------------------|
+| ≤1       | 1.0         | Active            |
+| ≤7       | 0.8         | Recent            |
+| ≤30      | 0.5         | Decaying          |
+| ≤90      | 0.2         | Weak              |
+| >90      | 0           | Archived (deleted) |
 ```
 
 ### generateContextSummary
 
-生成 Agent 上下文摘要。
+Generates a context summary for agent injection.
 
 ```
-算法:
-1. 取全部记忆, 按 access_count DESC, priority DESC 排序
-2. 截取 top-N
-3. 每条截断 150 字符
-4. 格式: "- [name] content..."
+Algorithm:
+1. Sort all memories by access_count DESC, priority DESC
+2. Truncate to top-N
+3. Truncate each to 150 chars
+4. Format: "- [name] content..."
 ```
 
 ---
 
-## Hook 系统
+## Hook System
 
-配置位置: `~/.claude/settings.json`
+Configuration location: `~/.claude/settings.json`
 
 ```json
 {
@@ -402,125 +402,126 @@ Ebbinghaus 遗忘曲线判定记忆是否归档。
 }
 ```
 
-### 生命周期
+### Lifecycle
 
 ```
-SessionStart  → 加载 top-5 记忆 → 注入 Agent 上下文 (stdout)
+SessionStart  → Load top-5 memories → Inject into agent context (stdout)
    ↓
-Agent 工作    → 调 memory_store / memory_search / ...
+Agent works   → Calls memory_store / memory_search / etc.
    ↓
-PreCompact    → 加载 top-8 记忆 + 注入存储指令 → Agent 自动保存
+PreCompact    → Load top-8 memories + inject save instruction → Agent auto-saves
    ↓
-Stop          → autoPriority 重算 + autoDecay 检查 + 归档过期记忆
+Stop          → autoPriority recalc + autoDecay check + archive expired
    ↓
-(下次) SessionStart → 记忆已保留 ✅
+(next) SessionStart → Memories preserved ✅
 ```
 
-### 关键设计决策
+### Key Design Decision
 
-**为什么 PreCompact 而非 Stop 做 auto-capture？**
-Stop hook 只在正常退出时触发。`kill` / 关终端窗口 / 崩溃 → Stop 不跑。PreCompact 在上下文快满时一定触发，此时进程还活着，Agent 能执行存储指令。
+**Why PreCompact instead of Stop for auto-capture?**
+
+The Stop hook only fires on graceful exit. `kill`, closing the terminal window, or crashes will skip it. PreCompact always fires when the context window approaches its limit — the process is still alive and the agent can execute the save instruction.
 
 ---
 
-## 存储层
+## Storage Layer
 
-### Free 层 (本地 Markdown)
+### Free Tier (Local Markdown)
 
-- 路径: `~/.memory-forge/memories/{id}.md`
-- 格式: 类 YAML frontmatter + Markdown body
-- 编码: UTF-8
-- 权限: 用户文件系统控制
-- 网络: 零
+- Path: `~/.memory-forge/memories/{id}.md`
+- Format: YAML-like frontmatter + Markdown body
+- Encoding: UTF-8
+- Permissions: user filesystem control
+- Network: zero
 
-### Pro 层 (Shelby 云)
+### Pro Tier (Shelby Cloud)
 
-- SDK: `@shelby-protocol/sdk` ^0.3.1 (optionalDep)
-- 网络: Shelbynet 测试网
-- 认证: API Key + Ed25519 链上账户
-- Blob 格式: `memories/{id}.json` (JSON)
-- 过期: 365 天
-- 数据流: 双向同步 (session 启动时 ↓↑, memory_store 时 ↑)
+- SDK: `@shelby-protocol/sdk` ^0.3.1 (optionalDependency)
+- Network: Shelbynet testnet
+- Auth: API Key + Ed25519 on-chain account
+- Blob format: `memories/{id}.json` (JSON)
+- Expiry: 365 days
+- Data flow: bidirectional sync (↓↑ on session start, ↑ on memory_store)
 
-**Pro 数据流:**
+**Pro data flow:**
 ```
 SessionStart:
   syncAll():
-    ↓ listBlobs() → 获取远程记忆列表
-    ↓ downloadMemory() → 下载本地不存在的 (30s timeout)
-    ↑ uploadMemory() → 上传本地有而远程无的
-    → 双向同步完成
+    ↓ listBlobs() → fetch remote memory list
+    ↓ downloadMemory() → download anything not local (30s timeout)
+    ↑ uploadMemory() → upload local-only memories
+    → Bidirectional sync complete
 
 memory_store:
-  saveMemory() → 本地
-  uploadMemory() → Shelby (fire-and-forget, 失败不阻塞)
+  saveMemory() → local
+  uploadMemory() → Shelby (fire-and-forget, failure is non-blocking)
 ```
 
 ---
 
-## 嵌入引擎
+## Embedding Engine
 
-### 技术栈
+### Tech Stack
 
-- 库: `@huggingface/transformers` ^3.0.0
-- 模型: Xenova/all-MiniLM-L6-v2
-- 大小: ~23MB (首次下载, 后续缓存)
-- 维度: 384
-- 池化: mean pooling + L2 normalize
+- Library: `@huggingface/transformers` ^3.0.0
+- Model: Xenova/all-MiniLM-L6-v2
+- Size: ~23MB (one-time download, cached thereafter)
+- Dimensions: 384
+- Pooling: mean pooling + L2 normalization
 
-### 降级策略
+### Degradation Strategy
 
 ```
-加载模型
-  → 成功: cos similarity search
-  → 失败: keyword matching (Jaccard)
-     + 5 分钟自动重试
-     + sleep(300s) 防止请求风暴
+Load model
+  → Success: cosine similarity search
+  → Failure: keyword matching (Jaccard)
+     + 5-minute auto-retry
+     + sleep(300s) to prevent request storms
 ```
 
-### 性能
+### Performance
 
-- 首次加载: 3-10s (取决于网络, 23MB 下载)
-- 后续推理: < 100ms
-- 降级关键词: < 10ms
-- 模型缓存: Transformers.js 内置缓存
+- First load: 3–10s (depends on network; 23MB download)
+- Subsequent inference: < 100ms
+- Keyword fallback: < 10ms
+- Model caching: Transformers.js built-in cache
 
 ---
 
-## 安全模型
+## Security Model
 
-### Free 层
+### Free Tier
 
-- 全部数据在 `~/.memory-forge/` 目录
-- 零持续网络请求
-- 唯一网络: 首次模型下载 (HuggingFace CDN, 23MB)
-- 模型下载失败 → 关键词降级, 零功能损失
+- All data in `~/.memory-forge/` directory
+- Zero ongoing network requests
+- Only network: one-time model download (HuggingFace CDN, 23MB)
+- Model download failure → keyword fallback, zero functionality loss
 
-### Pro 层
+### Pro Tier
 
-- API Key: 环境变量 `SHELBY_API_KEY` 注入, 不落盘
-- 私钥: `~/.memory-forge/pro.json`, Ed25519 格式
-- 传输: HTTPS (Shelbynet API)
-- 链上: 每条记忆 → Aptos blob upload transaction
-- 删除: tombstone blob (标记删除, 链上不可篡改)
+- API Key: `SHELBY_API_KEY` environment variable only — never written to disk
+- Private Key: `~/.memory-forge/pro.json`, Ed25519 format
+- Transport: HTTPS (Shelbynet API)
+- On-chain: each memory → Aptos blob upload transaction
+- Deletion: tombstone blob (marks deletion; chain is immutable)
 
-### 记忆权限
+### Memory Permissions
 
-- 文件系统权限 = 记忆权限 (Free)
-- 链上账户签名 = 记忆权限 (Pro)
-- 无内置认证/授权层 (Agent 已通过 Claude Code 认证)
+- Filesystem permissions = memory permissions (Free)
+- On-chain account signature = memory permissions (Pro)
+- No built-in auth layer (agent is already authenticated by Claude Code)
 
 ---
 
-## 错误处理与降级
-
-| 场景 | 行为 | 影响 |
-|------|------|------|
-| 嵌入模型下载失败 | 关键词搜索, 5min 重试 | 搜索精度下降, 功能可用 |
-| 嵌入模型推理失败 | 返回 null, 关键词降级 | 单次查询降级 |
-| Shelby 上传失败 | console.error, 不阻塞 | Pro 同步不同步, 本地完好 |
-| Shelby 下载超时 | 30s timeout, 返回 null | 该条不同步, 其他正常 |
-| Shelby 链上 gas 不足 | 上传失败 + 错误消息 | Pro 不可用, Free 完好 |
-| parseMemoryFile 损坏 | 跳过该文件, 返回 null | 损坏文件被忽略 |
-| 磁盘写失败 | 静默失败 | 记忆丢失 (极罕见) |
-| LRU 满 5000 | 淘汰最低 access_count × priority | 旧记忆清出内存, 磁盘保留 |
+## Error Handling & Degradation
+
+| Scenario | Behavior | Impact |
+|----------|----------|--------|
+| Embedding model download fails | Keyword search, 5min retry | Lower search precision, functional |
+| Embedding model inference fails | Return null, keyword fallback | Single query degraded |
+| Shelby upload fails | console.error, non-blocking | Pro sync delayed, local intact |
+| Shelby download timeout | 30s timeout, return null | That memory skipped, others OK |
+| Shelby on-chain gas insufficient | Upload fails + error message | Pro unavailable, Free intact |
+| parseMemoryFile corrupt | Skip file, return null | Corrupt file ignored |
+| Disk write fails | Silent failure | Memory lost (extremely rare) |
+| LRU at 5,000 limit | Evict lowest access_count × priority | Old memories evicted from cache, disk preserved |

package/TUTORIAL.md

@@ -1,353 +1,349 @@
-# MemoryForge 使用教程
+# MemoryForge — Tutorial
 
-> 一条命令。零配置。AI Agent 从此拥有持久记忆。
+> One command. Zero config. Your AI agent now has persistent memory.
 
-## 目录
+## Table of Contents
 
-1. [快速开始](#快速开始)
-2. [工作原理](#工作原理)
-3. [日常使用](#日常使用)
-4. [Pro 版 (云同步)](#pro-版-云同步)
-5. [管理记忆](#管理记忆)
-6. [最佳实践](#最佳实践)
-7. [排错指南](#排错指南)
-8. [卸载](#卸载)
+1. [Quick Start](#quick-start)
+2. [How It Works](#how-it-works)
+3. [Daily Use](#daily-use)
+4. [Pro Tier (Cloud Sync)](#pro-tier-cloud-sync)
+5. [Managing Memories](#managing-memories)
+6. [Best Practices](#best-practices)
+7. [Troubleshooting](#troubleshooting)
+8. [Uninstall](#uninstall)
 
 ---
 
-## 快速开始
+## Quick Start
 
-### 安装
+### Install
 
 ```bash
 npx memory-forge setup
 ```
 
-一步完成:
-- 安装 Claude Code hooks (SessionStart / Stop / PreCompact)
-- 自动导入已有规则 (CLAUDE.md / .cursor/rules / .gitconfig)
-- 预加载嵌入模型 (23MB, 首次, 后续离线)
-- 全局安装 `memory-forge` 命令
+This single command:
+- Installs Claude Code hooks (SessionStart / Stop / PreCompact)
+- Auto-imports existing rules (CLAUDE.md / .cursor/rules / .gitconfig)
+- Preloads the embedding model (23MB, one-time, offline thereafter)
+- Globally installs the `memory-forge` command
 
-**支持平台:** Claude Code (全平台), Cursor (通过 MCP), Windsurf, VS Code。
+**Supported platforms:** Claude Code (all platforms), Cursor (via MCP), Windsurf, VS Code.
 
-### 验证安装
+### Verify
 
-重启 Claude Code，你会看到:
+Restart Claude Code. You should see:
 
 ```
 - [Git User Info] Git user email: xxx
 - [Claude Code Rules] For independent parallel tasks...
 ```
 
-这表示 SessionStart hook 已生效，Agent 加载了你的记忆。
+This means the SessionStart hook is active and the agent has loaded your memories.
 
 ---
 
-## 工作原理
+## How It Works
 
-### 自动化记忆生命周期
+### Automated Memory Lifecycle
 
 ```
-你打开 Claude Code
-  → Agent 自动加载你的偏好和项目上下文
-  
-你工作...
-  → Agent 自动记住你的编码风格、技术决策、项目偏好
-  
-上下文快满时 (PreCompact)
-  → Agent 自动保存关键信息到记忆库
-  → 即使你强制关终端，记忆也不会丢失
-
-你关闭 Claude Code (Stop)
-  → 自动更新记忆优先级 (常用记忆提高权重)
-  → 自动归档 90 天未用的旧记忆
-
-下次打开
-  → Agent 又什么都记得 ✅
+You open Claude Code
+  → Agent auto-loads your preferences and project context
+
+You work...
+  → Agent automatically remembers your coding style, technical decisions, project preferences
+
+Context window nearly full (PreCompact)
+  → Agent auto-saves critical information to the memory store
+  → Even if you force-close the terminal, memories survive
+
+You close Claude Code (Stop)
+  → Auto-update memory priorities (frequently-used memories get higher weight)
+  → Auto-archive memories unused for 90+ days
+
+Next session
+  → Agent remembers everything ✅
 ```
 
-### 你什么都不用做
+### You Do Nothing
 
-Agent 自动:
-- **存储**: 你提到偏好、决策、教训 → Agent 调 `memory_store`
-- **搜索**: 需要回忆之前的事 → Agent 调 `memory_search`
-- **维护**: 优先级调整、过期清理 → 自动
+The agent automatically:
+- **Stores**: you mention preferences, decisions, lessons → agent calls `memory_store`
+- **Searches**: needs to recall something → agent calls `memory_search`
+- **Maintains**: priority adjustment, expiry cleanup → fully automatic
 
 ---
 
-## 日常使用
+## Daily Use
 
-### 基本交互
+### Basic Interaction
 
 ```
-你: "我偏好 camelCase 命名，单引号，2 空格缩进"
+You: "I prefer camelCase naming, single quotes, 2-space indent"
 
-Agent 自动调 memory_store → 记忆保存 ✅
-下次写代码，Agent 自动遵循你的偏好。
+Agent auto-calls memory_store → memory saved ✅
+Next time you write code, the agent follows your preferences automatically.
 
 ---
 
-你: "之前那个 token 刷新 bug 怎么修的？"
+You: "How did we fix that token refresh bug?"
 
-Agent 调 memory_search → 找到相关记忆
-"6 月 15 日，你在 auth.ts 修了 token 过期判断从 < 改为 <="
+Agent calls memory_search → finds relevant memory
+"On June 15, you fixed auth.ts — the token expiry check was using < instead of <="
 
 ---
 
-你: "帮我重构认证模块"
+You: "Help me refactor the auth module"
 
-Agent 调 memory_context → 加载上下文
-"好的。根据之前的记录，项目用 React 19 + JWT + refresh token 模式。从 auth.ts 开始？"
+Agent calls memory_context → loads context
+"Got it. Based on prior records, this project uses React 19 + JWT + refresh token pattern. Start from auth.ts?"
 ```
 
-### 主动使用
+### Explicit Commands
 
-你也可以明确让 Agent 操作记忆:
+You can also tell the agent explicitly:
 
 ```
-"存储一条记忆: 生产数据库用 PostgreSQL 16，连接串在 .env.production"
-"搜索关于部署流程的记忆"
-"列出我所有的记忆"
-"导出全部记忆为 Markdown"
-"删除 ID 为 xxx 的旧记忆"
+"Store a memory: production database uses PostgreSQL 16, connection string in .env.production"
+"Search for memories about deployment"
+"List all my memories"
+"Export all memories as Markdown"
+"Forget the memory with ID xxx"
 ```
 
 ---
 
-## Pro 版 (云同步)
+## Pro Tier (Cloud Sync)
 
-### 什么情况需要 Pro
+### When You Need Pro
 
-- 你有多台电脑，想在设备间共享记忆
-- 你担心硬盘故障丢失记忆
-- 你想和队友共享项目记忆
+- You use multiple computers and want cross-device memory sync
+- You're worried about disk failure losing your memories
+- You want shared project memories with teammates
 
-### 开通 Pro
+### Activating Pro
 
 ```bash
-# 1. 获取 API Key
-# 访问 https://docs.shelby.xyz/sdks/typescript/acquire-api-keys
+# 1. Get an API Key
+# Visit https://docs.shelby.xyz/sdks/typescript/acquire-api-keys
 
-# 2. 激活 Pro
+# 2. Activate Pro
 SHELBY_API_KEY="your-api-key" memory-forge pro
 
-# 3. 第一次需要充值 APT + ShelbyUSD (测试网水龙头)
-# 地址会打印在屏幕上，去 faucet 领取:
+# 3. First time: fund your account with APT + ShelbyUSD (testnet faucet)
+# The address will be printed. Go to the faucet:
 #   APT:       https://docs.shelby.xyz/apis/faucet/aptos
 #   ShelbyUSD: https://docs.shelby.xyz/apis/faucet/shelbyusd
 
-# 4. 领取后重新运行同步
+# 4. After claiming tokens, sync again
 SHELBY_API_KEY="your-api-key" memory-forge pro
 ```
 
-### 多设备同步
+### Cross-Device Sync
 
 ```
-设备 A: 激活 Pro → 工作 → 记忆自动上传
-设备 B: 设置 SHELBY_API_KEY 环境变量 → 安装 → 记忆自动下载
-  → Agent 在设备 B 上也能记住一切 ✅
+Device A: Activate Pro → work → memories auto-upload
+Device B: Set SHELBY_API_KEY env var → install → memories auto-download
+  → Agent on device B remembers everything ✅
 ```
 
-### 环境变量
+### Environment Variable
 
-建议写入 shell 配置文件:
+Add to your shell config for permanent setup:
 
 ```bash
-# ~/.bashrc 或 ~/.zshrc
+# ~/.bashrc or ~/.zshrc
 export SHELBY_API_KEY="your-api-key"
 ```
 
-这样每次 Agent 启动自动启用 Pro 同步，无需手动运行命令。
+The agent will auto-sync on every session start.
 
 ---
 
-## 管理记忆
+## Managing Memories
 
-### 查看记忆
+### Viewing Memories
 
 ```bash
-# 查看记忆文件
+# List memory files
 ls ~/.memory-forge/memories/
 
-# 读某条记忆
+# Read a specific memory
 cat ~/.memory-forge/memories/{id}.md
 ```
 
-记忆文件是人类可读的 Markdown，可以直接编辑。
+Memory files are human-readable Markdown. You can edit them directly.
 
-### 导出
+### Exporting
 
 ```
-# Agent 方式
-"导出全部记忆为 JSON"
-"导出关于认证的记忆为 Markdown"
-
-# 命令行方式
-# JSON 导出在 Agent 调用 memory_export 后获取
+# Via agent
+"Export all memories as JSON"
+"Export auth-related memories as Markdown"
 ```
 
-### 备份
+### Backup
 
 ```bash
-# 本地备份 (Free 层)
+# Local backup (Free tier)
 cp -r ~/.memory-forge/memories/ ~/backup/
 
-# Pro 层自动备份到 Shelby 云
+# Pro tier auto-backs up to Shelby cloud
 ```
 
-### 清理
+### Cleanup
 
 ```bash
-# 删除全部本地记忆
+# Delete all local memories
 rm -rf ~/.memory-forge/memories/*.md
 
-# 删除单条
+# Delete a single memory
 rm ~/.memory-forge/memories/{id}.md
 
-# Pro 账户重置
+# Reset Pro account
 rm ~/.memory-forge/pro.json
 ```
 
 ---
 
-## 最佳实践
+## Best Practices
 
-### 什么值得记
+### What's Worth Remembering
 
-| 值得记 | 不值得记 |
-|--------|---------|
-| 编码风格偏好 | 单次 debug 过程 |
-| 项目架构决策 | 临时实验代码 |
-| 团队约定 | 过时的配置 |
-| 常用命令和流程 | 纯事实性知识 |
-| 踩过的坑和解决方案 | 一次性任务 |
+| Worth It | Not Worth It |
+|----------|--------------|
+| Coding style preferences | One-off debug sessions |
+| Project architecture decisions | Temporary experimental code |
+| Team conventions | Outdated configuration |
+| Frequently-used commands and workflows | Pure factual knowledge |
+| Lessons learned and solutions found | One-time tasks |
 
-### 记忆质量
+### Memory Quality
 
 ```
-✅ 好: "项目用 PostgreSQL 16 + Prisma ORM，连接池上限 20"
-❌ 差: "数据库是 pg"
+✅ Good: "Project uses PostgreSQL 16 + Prisma ORM, connection pool limit 20"
+❌ Bad:  "database is pg"
 
-✅ 好: "用户偏好 camelCase，单引号，2 空格，React 19 + TypeScript strict"
-❌ 差: "用 camelCase"
+✅ Good: "User prefers camelCase, single quotes, 2-space indent, React 19 + TypeScript strict"
+❌ Bad:  "uses camelCase"
 
-✅ 好: "6/26 决定用 Redis 缓存 token，因为 DB 查询太慢 (>500ms)"
-❌ 差: "用了 Redis"
+✅ Good: "6/26 — decided to cache tokens in Redis because DB queries were >500ms"
+❌ Bad:  "added Redis"
 ```
 
-### 定期维护
+### Periodic Maintenance
 
-每月做一次记忆清理:
+Do a memory cleanup once a month:
 
 ```
-"查看我所有记忆，标记哪些过时了或不再需要"
-"删除 3 个月前关于旧项目的记忆"
+"Review all my memories and flag anything outdated or no longer needed"
+"Forget memories related to projects I no longer work on"
 ```
 
 ---
 
-## 排错指南
+## Troubleshooting
 
-### Hook 不生效
+### Hooks Not Working
 
-**症状:** 打开 Claude Code 看不到记忆加载。
+**Symptom:** Opening Claude Code shows no memory loading.
 
-**解决:**
 ```bash
-# 1. 检查 hook 配置
+# 1. Check hook configuration
 memory-forge hook session-start
 
-# 2. 重新安装 hooks
+# 2. Reinstall hooks
 memory-forge setup
 
-# 3. 确认 settings.json
+# 3. Verify settings.json
 cat ~/.claude/settings.json | grep memory-forge
 
-# 4. 重启 Claude Code
+# 4. Restart Claude Code
 ```
 
-### Stop hook 报错
+### Stop Hook Error
 
-**症状:** 关闭时显示 "Stop hook error"。
+**Symptom:** "Stop hook error" on session close.
 
 ```bash
-# 确认全局安装
+# Confirm global install
 npm ls -g memory-forge
 
-# 如果不是最新版
+# If not latest
 npm i -g memory-forge@latest
 
-# 检查 hook 命令格式
-# settings.json 中应该是 "memory-forge hook stop"，不是 "npx memory-forge hook stop"
+# Check hook command format
+# settings.json should have "memory-forge hook stop", not "npx memory-forge hook stop"
 ```
 
-### 记忆搜索不准确
+### Inaccurate Search Results
 
-**症状:** memory_search 返回无关结果。
+**Symptom:** `memory_search` returns irrelevant results.
 
 ```bash
-# 检查嵌入模型是否下载成功
-# 如果看到 "[MemoryForge] Falling back to keyword matching"
-# → 模型下载失败，使用关键词模式
+# Check if embedding model downloaded successfully
+# If you see "[MemoryForge] Falling back to keyword matching"
+# → Model download failed; keyword mode is active
 
-# 解决: 等待 5 分钟自动重试，或手动触发重试
-# 模型大小 23MB，确保网络正常
+# Solution: wait 5 minutes for auto-retry, or trigger a retry manually
+# Model size is 23MB — ensure network is working
 ```
 
-### Pro 同步失败
+### Pro Sync Fails
 
-**症状:** "Shelby upload failed: INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEE"
+**Symptom:** "Shelby upload failed: INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEE"
 
 ```bash
-# 检查账户余额
-# 去 faucet 领取 APT + ShelbyUSD
-# 然后重新运行 pro 命令
+# Check account balance
+# Visit the faucet to claim APT + ShelbyUSD
+# Then re-run pro
 
 SHELBY_API_KEY="your-key" memory-forge pro
 ```
 
-### 重复记忆
+### Duplicate Memories
 
-**症状:** memory_list 显示重复的相似记忆。
+**Symptom:** `memory_list` shows repeated similar memories.
 
 ```bash
-# 0.1.6+ 已根因修复。如果仍有:
-# 1. 升级到最新版
+# 0.1.6+ has a root-cause fix. If you still see duplicates:
+# 1. Upgrade to latest
 npm i -g memory-forge@latest
 memory-forge setup
 
-# 2. 手动清理
-# 删除 ~/.memory-forge/memories/ 中的重复 .md 文件
+# 2. Manual cleanup
+# Delete duplicate .md files in ~/.memory-forge/memories/
 ```
 
-### 完全重置
+### Full Reset
 
 ```bash
-# 1. 删记忆
+# 1. Delete memories
 rm -rf ~/.memory-forge/memories/*.md
 
-# 2. 删 Pro 账户 (可选)
+# 2. Delete Pro account (optional)
 rm -f ~/.memory-forge/pro.json
 
-# 3. 清除 hooks
-# 编辑 ~/.claude/settings.json, 删除含 "memory-forge" 的条目
+# 3. Clear hooks
+# Edit ~/.claude/settings.json, remove all entries containing "memory-forge"
 
-# 4. 重装
+# 4. Reinstall
 memory-forge setup
 ```
 
 ---
 
-## 卸载
+## Uninstall
 
 ```bash
-# 删除所有本地数据
+# Remove all local data
 rm -rf ~/.memory-forge/
 
-# 编辑 ~/.claude/settings.json
-# 删除 hooks 中包含 "memory-forge" 的所有条目
+# Edit ~/.claude/settings.json
+# Remove all hook entries containing "memory-forge"
 
-# 卸载全局命令
+# Uninstall global command
 npm uninstall -g memory-forge
 ```

package/dist/index.js

@@ -95,7 +95,7 @@ function startMcpServer() {
         store.add(m);
     }
     preload();
-    const server = new McpServer({ name: "memory-forge", version: "0.1.7" });
+    const server = new McpServer({ name: "memory-forge", version: "0.2.0" });
     // ── memory_store ──────────────────────────────────────────
     server.registerTool("memory_store", {
         title: "存储记忆",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-forge",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "Forge persistent memories for your AI agent. 8 MCP tools + 5 auto-engines. Powered by Shelby decentralized cloud.",
   "type": "module",
   "license": "MIT",