memory-forge 0.1.8 → 0.2.0

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

@@ -0,0 +1,527 @@
+# MemoryForge — Technical Documentation
+
+> Version 0.1.9 | 8 MCP Tools + 5 Auto-Engines | Free (local) + Pro (Shelby cloud)
+
+## Table of Contents
+
+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 protocol
+├─────────────────────────────────────┤
+│  CLI Router (index.ts)              │
+│  setup / pro / hook / MCP Server    │
+├─────────────────────────────────────┤
+│  8 MCP Tools                        │
+│  store / search / recall / list     │
+│  forget / context / export / share  │
+├──────────────┬──────────────────────┤
+│  Free Tier   │  Pro Tier             │
+│  MemoryStore │  ShelbyNodeClient     │
+│  local .md   │  upload/download/list │
+├──────────────┴──────────────────────┤
+│  5 Auto-Engines                     │
+│  name → merge → priority → decay    │
+│  → contextSummary                   │
+├─────────────────────────────────────┤
+│  Embedding Engine                   │
+│  Transformers.js / MiniLM-L6-v2     │
+│  384-dim vectors, cosine similarity │
+│  fallback: keyword matching         │
+└─────────────────────────────────────┘
+```
+
+### Source File Structure
+
+```
+agentvault/src/
+├── 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 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 Interface
+
+```typescript
+interface Memory {
+  id: string;              // UUID v4
+  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
+
+Path: `~/.memory-forge/memories/{id}.md`
+
+```markdown
+# Memory Name
+> category: user-preference
+> tags: coding-style, javascript
+> priority: 8
+> created: 2026-06-26T10:00:00.000Z
+> access_count: 5
+> last_accessed: 2026-06-26T12:00:00.000Z
+
+User prefers camelCase naming, single quotes, and 2-space indent.
+```
+
+### MemoryStore Index
+
+- `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 Tool API Reference
+
+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
+{
+  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
+}
+
+// Output (success)
+{
+  success: true;
+  merged?: boolean;       // true if merged with existing (>80% overlap)
+  memory_id: string;
+  name: string;
+  preview: string;        // first 200 chars
+}
+```
+
+**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, 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)
+}
+
+// Output
+{
+  query: string;
+  count: number;
+  results: [{
+    memory_id: string;
+    name: string;
+    similarity: number;    // cosine similarity (0 if keyword fallback)
+    content: string;
+    _method: "vector" | "keyword";
+  }];
+  hint: string | null;     // "No relevant memories found." if empty
+}
+```
+
+**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
+
+Exact retrieval by memory ID.
+
+```typescript
+// Input
+{ memory_id: string }
+
+// Output (success)
+{
+  memory_id, name, content, category, tags,
+  priority, created_at, access_count
+}
+
+// Output (not found)
+{ error: "Not found", memory_id }
+```
+
+### memory_list
+
+List memories with pagination and filtering.
+
+```typescript
+// Input
+{
+  category?: string;    // filter
+  tags?: string[];      // filter (OR match)
+  limit?: number;       // 1–100, default: 20
+  offset?: number;      // default: 0
+}
+
+// Output
+{
+  total: number;        // total memory count
+  count: number;        // current page count
+  memories: [{
+    memory_id, name, category,
+    tags, priority,
+    preview: string;    // first 100 chars
+  }];
+}
+```
+
+### memory_forget
+
+Delete a memory (local file + in-memory cache).
+
+```typescript
+// Input
+{ memory_id: string }
+
+// Output
+{
+  success: boolean;
+  memory_id: string;
+  action: "deleted" | "not_found";
+}
+```
+
+### memory_context
+
+Load current session context — returns top recently-accessed, high-priority memory summaries.
+
+```typescript
+// Input
+{ limit?: number;  // 1–20, default: 5 }
+
+// Output
+{
+  context_loaded: true;
+  memory_count: number;
+  context: string;  // format: "- [name] preview..."
+}
+```
+
+**Sort order:** `access_count` DESC, ties broken by `priority` DESC.
+
+### memory_export
+
+Export memories as JSON or Markdown.
+
+```typescript
+// Input
+{
+  memory_ids?: string[];  // omit to export all
+  format?: "json" | "markdown";  // default: "json"
+}
+
+// Output (JSON)
+{
+  exported_at: string;
+  version: "memory-forge-1.0";
+  count: number;
+  memories: [{ id, name, content, category, tags, priority, created_at }];
+}
+
+// Output (Markdown)
+# Memory Name
+> category: x | tags: a, b | priority: 7
+...
+---
+```
+
+### memory_share
+
+Package a single memory for import by teammates.
+
+```typescript
+// Input
+{
+  memory_id: string;
+  recipient?: string;
+  note?: string;
+}
+
+// Output
+{
+  type: "memory-forge-share";
+  version: "1.0";
+  shared_at: string;
+  recipient: string | null;
+  note: string | null;
+  memory: { name, content, category, tags };
+  import_instruction: "Use memory_store with this content to import.";
+}
+```
+
+---
+
+## Auto-Engines
+
+All engines are located in `src/auto/index.ts`.
+
+### autoName
+
+Extracts a human-readable name from content.
+
+```
+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.
+
+```
+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
+
+Computes priority score (1–10) based on the Ebbinghaus forgetting curve.
+
+```
+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
+
+Determines whether a memory should be archived.
+
+```
+| 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
+
+Generates a context summary for agent injection.
+
+```
+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 System
+
+Configuration location: `~/.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{"type": "command", "command": "memory-forge hook session-start"}]
+    }],
+    "Stop": [{
+      "hooks": [{"type": "command", "command": "memory-forge hook stop"}]
+    }],
+    "PreCompact": [{
+      "hooks": [{"type": "command", "command": "memory-forge hook pre-compact"}]
+    }]
+  }
+}
+```
+
+### Lifecycle
+
+```
+SessionStart  → Load top-5 memories → Inject into agent context (stdout)
+   ↓
+Agent works   → Calls memory_store / memory_search / etc.
+   ↓
+PreCompact    → Load top-8 memories + inject save instruction → Agent auto-saves
+   ↓
+Stop          → autoPriority recalc + autoDecay check + archive expired
+   ↓
+(next) SessionStart → Memories preserved ✅
+```
+
+### Key Design Decision
+
+**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 Tier (Local Markdown)
+
+- Path: `~/.memory-forge/memories/{id}.md`
+- Format: YAML-like frontmatter + Markdown body
+- Encoding: UTF-8
+- Permissions: user filesystem control
+- Network: zero
+
+### Pro Tier (Shelby Cloud)
+
+- 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 data flow:**
+```
+SessionStart:
+  syncAll():
+    ↓ listBlobs() → fetch remote memory list
+    ↓ downloadMemory() → download anything not local (30s timeout)
+    ↑ uploadMemory() → upload local-only memories
+    → Bidirectional sync complete
+
+memory_store:
+  saveMemory() → local
+  uploadMemory() → Shelby (fire-and-forget, failure is non-blocking)
+```
+
+---
+
+## Embedding Engine
+
+### Tech Stack
+
+- 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
+
+```
+Load model
+  → Success: cosine similarity search
+  → Failure: keyword matching (Jaccard)
+     + 5-minute auto-retry
+     + sleep(300s) to prevent request storms
+```
+
+### Performance
+
+- 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 Tier
+
+- 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 Tier
+
+- 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
+
+- Filesystem permissions = memory permissions (Free)
+- On-chain account signature = memory permissions (Pro)
+- No built-in auth layer (agent is already authenticated by Claude Code)
+
+---
+
+## 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

@@ -0,0 +1,349 @@
+# MemoryForge — Tutorial
+
+> One command. Zero config. Your AI agent now has persistent memory.
+
+## Table of Contents
+
+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
+```
+
+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
+
+**Supported platforms:** Claude Code (all platforms), Cursor (via MCP), Windsurf, VS Code.
+
+### Verify
+
+Restart Claude Code. You should see:
+
+```
+- [Git User Info] Git user email: xxx
+- [Claude Code Rules] For independent parallel tasks...
+```
+
+This means the SessionStart hook is active and the agent has loaded your memories.
+
+---
+
+## How It Works
+
+### Automated Memory Lifecycle
+
+```
+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
+
+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
+
+```
+You: "I prefer camelCase naming, single quotes, 2-space indent"
+
+Agent auto-calls memory_store → memory saved ✅
+Next time you write code, the agent follows your preferences automatically.
+
+---
+
+You: "How did we fix that token refresh bug?"
+
+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 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
+
+You can also tell the agent explicitly:
+
+```
+"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 Tier (Cloud Sync)
+
+### 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
+
+### Activating Pro
+
+```bash
+# 1. Get an API Key
+# Visit https://docs.shelby.xyz/sdks/typescript/acquire-api-keys
+
+# 2. Activate Pro
+SHELBY_API_KEY="your-api-key" memory-forge pro
+
+# 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. After claiming tokens, sync again
+SHELBY_API_KEY="your-api-key" memory-forge pro
+```
+
+### Cross-Device Sync
+
+```
+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
+
+Add to your shell config for permanent setup:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+export SHELBY_API_KEY="your-api-key"
+```
+
+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
+```
+
+Memory files are human-readable Markdown. You can edit them directly.
+
+### Exporting
+
+```
+# Via agent
+"Export all memories as JSON"
+"Export auth-related memories as Markdown"
+```
+
+### Backup
+
+```bash
+# Local backup (Free tier)
+cp -r ~/.memory-forge/memories/ ~/backup/
+
+# 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
+
+# Reset Pro account
+rm ~/.memory-forge/pro.json
+```
+
+---
+
+## Best Practices
+
+### What's Worth Remembering
+
+| 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
+
+```
+✅ Good: "Project uses PostgreSQL 16 + Prisma ORM, connection pool limit 20"
+❌ Bad:  "database is pg"
+
+✅ Good: "User prefers camelCase, single quotes, 2-space indent, React 19 + TypeScript strict"
+❌ Bad:  "uses camelCase"
+
+✅ 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:
+
+```
+"Review all my memories and flag anything outdated or no longer needed"
+"Forget memories related to projects I no longer work on"
+```
+
+---
+
+## Troubleshooting
+
+### Hooks Not Working
+
+**Symptom:** Opening Claude Code shows no memory loading.
+
+```bash
+# 1. Check hook configuration
+memory-forge hook session-start
+
+# 2. Reinstall hooks
+memory-forge setup
+
+# 3. Verify settings.json
+cat ~/.claude/settings.json | grep memory-forge
+
+# 4. Restart Claude Code
+```
+
+### 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
+
+# Check hook command format
+# settings.json should have "memory-forge hook stop", not "npx memory-forge hook stop"
+```
+
+### Inaccurate Search Results
+
+**Symptom:** `memory_search` returns irrelevant results.
+
+```bash
+# Check if embedding model downloaded successfully
+# If you see "[MemoryForge] Falling back to keyword matching"
+# → Model download failed; keyword mode is active
+
+# Solution: wait 5 minutes for auto-retry, or trigger a retry manually
+# Model size is 23MB — ensure network is working
+```
+
+### Pro Sync Fails
+
+**Symptom:** "Shelby upload failed: INSUFFICIENT_BALANCE_FOR_TRANSACTION_FEE"
+
+```bash
+# Check account balance
+# Visit the faucet to claim APT + ShelbyUSD
+# Then re-run pro
+
+SHELBY_API_KEY="your-key" memory-forge pro
+```
+
+### Duplicate Memories
+
+**Symptom:** `memory_list` shows repeated similar memories.
+
+```bash
+# 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. Manual cleanup
+# Delete duplicate .md files in ~/.memory-forge/memories/
+```
+
+### Full Reset
+
+```bash
+# 1. Delete memories
+rm -rf ~/.memory-forge/memories/*.md
+
+# 2. Delete Pro account (optional)
+rm -f ~/.memory-forge/pro.json
+
+# 3. Clear hooks
+# Edit ~/.claude/settings.json, remove all entries containing "memory-forge"
+
+# 4. Reinstall
+memory-forge setup
+```
+
+---
+
+## Uninstall
+
+```bash
+# Remove all local data
+rm -rf ~/.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.8",
+  "version": "0.2.0",
   "description": "Forge persistent memories for your AI agent. 8 MCP tools + 5 auto-engines. Powered by Shelby decentralized cloud.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,8 @@
   "files": [
     "dist/",
     "README.md",
+    "TECHNICAL.md",
+    "TUTORIAL.md",
     "LICENSE"
   ],
   "scripts": {