@synth-coder/memhub 0.2.3 → 0.2.5

package/README.md

@@ -1,195 +1,284 @@
-# MemHub
-
-Git-friendly memory MCP server for coding agents.
-
-MemHub stores decisions, preferences, and reusable knowledge as plain Markdown files with YAML front matter, so everything is easy to review, diff, and version with Git.
-
----
-
-## Why MemHub
-
-- **Git-native**: all memory is plain text files
-- **Agent-friendly**: exposed as MCP tools over stdio
-- **Human-readable**: YAML metadata + Markdown body
-- **Quality-gated**: lint + typecheck + tests + coverage gate
-
----
-
-## Features
-
-- Markdown-based memory storage (`.md`)
-- YAML Front Matter metadata (`id`, `session_id`, `entry_type`, `tags`, `category`, `importance`, timestamps)
-- STM-first 2-tool interface: `memory_load` + `memory_update`
-- Concurrent CLI-safe storage layout: `YYYY-MM-DD/session_uuid/...`
-- MCP stdio server compatible with MCP clients
-
----
-
-## Quick Start
-
-### 1) Install from npm
-
-```bash
-npm i @synth-coder/memhub
-```
-
-### 2) Or install dependencies for local development
-
-```bash
-npm install
-```
-
-### 3) Build
-
-```bash
-npm run build
-```
-
-### 4) Run quality gate
-```bash
-npm run quality
-```
-
----
-
-## Use as MCP Server (stdio)
-
-### Option A: run directly via npx (recommended)
-
-```bash
-npx -y @synth-coder/memhub
-```
-
-> On Windows, do **not** append `memhub` after the package name.
-> If a source `.js` file opens in editor, upgrade to latest package version (`0.1.2+`) and retry.
-
-Example MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "memhub": {
-      "command": "npx",
-      "args": ["-y", "@synth-coder/memhub"],
-      "env": {
-        "MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
-        "MEMHUB_LOG_LEVEL": "info"
-      }
-    }
-  }
-}
-```
-
-### Option B: local repo run
-
-```json
-{
-  "mcpServers": {
-    "memhub": {
-      "command": "node",
-      "args": ["dist/src/server/mcp-server.js"]
-    }
-  }
-}
-```
-
----
-
-## Environment Variables
-
-- `MEMHUB_STORAGE_PATH` (default: `./memories`)
-- `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
-
----
-
-## Memory File Format
-
-```markdown
----
-id: "550e8400-e29b-41d4-a716-446655440000"
-created_at: "2026-03-03T08:00:00.000Z"
-updated_at: "2026-03-03T08:00:00.000Z"
-tags:
-  - architecture
-  - tdd
-category: "engineering"
-importance: 4
----
-
-# Contract-first MCP design
-
-Define tool contracts and schemas before implementation.
-```
-
-Filename format:
-
-```text
-YYYY-MM-DD-title-slug.md
-```
-
----
-
-## MCP Tools
-
-- `memory_load`  
-  First-turn tool. Load STM context for the current task/session.
-- `memory_update`  
-  Final-turn tool. Write back decisions, preferences, knowledge, and task-state updates.
-
-Calling policy: see `docs/tool-calling-policy.md`.
-
----
-
-## Development
-
-### Scripts
-
-```bash
-npm run build
-npm run lint
-npm run typecheck
-npm run test
-npm run test:coverage
-npm run quality
-```
-
-### Engineering Workflow
-
-- Contract-first (types + schema first)
-- TDD (`red -> green -> refactor`)
-- Quality gate enforced before merge
-- Coverage threshold: **>= 80%**
-
----
-
-## Project Structure
-
-```text
-memhub/
-├── docs/
-├── src/
-│   ├── contracts/
-│   ├── server/
-│   ├── services/
-│   ├── storage/
-│   └── utils/
-├── test/
-└── .github/workflows/
-```
-
----
-
-## Roadmap
-
-- [x] Architecture and contracts
-- [x] Core storage/service/server implementation
-- [x] Quality gate (lint/typecheck/test/coverage)
-- [ ] Integration tests
-- [ ] Performance improvements
-- [x] npm release (`@synth-coder/memhub@0.2.0`)
-
----
-
-## License
-
-MIT
+# MemHub
+
+Git-friendly memory MCP server for coding agents.
+
+---
+
+## Quick Start
+
+### One-Line Setup
+
+Configure MemHub for your AI agent with a single command:
+
+```bash
+npx -y @synth-coder/memhub@latest init
+```
+
+This launches an interactive prompt to select your agent. MemHub will:
+1. Add MCP server config to your agent's configuration file
+2. Add MemHub usage instructions to your agent's rules file
+
+**Supported Agents:**
+
+| Agent | Config File | Instructions File |
+|-------|-------------|-------------------|
+| Claude Code | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursorrules` |
+| Cline | `~/.cline/mcp.json` | `~/.clinerules` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.windsurfrules` |
+| Factory Droid | `~/.factory/mcp.json` | `~/.factory/AGENTS.md` |
+| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` |
+| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
+
+### CLI Options
+
+```bash
+# Interactive selection (global - default)
+npx -y @synth-coder/memhub@latest init
+
+# Skip interactive prompt
+npx -y @synth-coder/memhub@latest init -a claude-code
+
+# Configure for current project only (local)
+npx -y @synth-coder/memhub@latest init -a cursor -l
+
+# Update existing configuration
+npx -y @synth-coder/memhub@latest init -a claude-code --force
+```
+
+| Option | Description |
+|--------|-------------|
+| `-a, --agent <name>` | Agent type (skip interactive) |
+| `-l, --local` | Configure for current project (default: global) |
+| `-f, --force` | Update existing configuration |
+
+### Run as MCP Server
+
+```bash
+npx -y @synth-coder/memhub@latest
+```
+
+> On Windows, do **not** append `memhub` after the package name.
+
+### Manual Configuration
+
+If you prefer manual setup, add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "memhub": {
+      "command": "npx",
+      "args": ["-y", "@synth-coder/memhub@latest"],
+      "env": {
+        "MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
+        "MEMHUB_LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+For Codex (`~/.codex/config.toml`), use TOML key `mcp_servers`:
+
+```toml
+[mcp_servers.memhub]
+command = "npx"
+args = ["-y", "@synth-coder/memhub@latest"]
+```
+
+---
+
+## Configure Your Agent
+
+Add the following to your coding agent's system prompt to enable persistent memory:
+
+```markdown
+## Memory System
+
+You have access to persistent memory across conversations. Use it wisely:
+
+- **Remember preferences** — Learn what the user likes and avoid repeating mistakes
+- **Recall decisions** — Build on past reasoning instead of starting from scratch
+- **Store context** — Project knowledge that survives session boundaries
+
+### When to Use
+
+#### `memory_load`
+
+Call when you need context from past conversations:
+- User references something from before
+- You're unsure about user preferences
+- A decision needs historical context
+
+Don't call for simple, self-contained tasks.
+
+#### `memory_update`
+
+Call when you discover something worth remembering:
+- User expresses a preference
+- You made a significant decision with reasoning
+- Project context changed
+
+Don't call for temporary or one-time information.
+
+### Principle
+
+Memory should feel natural — triggered by context, not by schedule. When in doubt, ask: "Would future me benefit from knowing this?"
+```
+
+---
+
+## MCP Tools
+
+- `memory_load`  
+  First-turn tool. Load STM context for the current task/session.
+- `memory_update`  
+  Final-turn tool. Write back decisions, preferences, knowledge, and task-state updates.
+
+See [docs/mcp-tools.md](docs/mcp-tools.md) for detailed API reference.
+
+---
+
+## Why MemHub
+
+Most AI memory tools rely on external APIs or simple keyword matching. MemHub is different:
+
+### Semantic Search with Local AI
+
+- **Vector Database**: Powered by LanceDB for fast similarity search
+- **Local Embeddings**: Quantized Transformers.js model runs entirely on your machine
+- **Zero API Costs**: No external services, no API keys, no rate limits
+- **Privacy First**: Your memories never leave your computer
+
+### Git-Native Storage
+
+- **Plain Text**: All memories are Markdown files with YAML front matter
+- **Version Control**: Commit, branch, review, and revert like any code
+- **Human Readable**: Browse and edit memories with any text editor
+- **Team Friendly**: Share memories via git repository
+
+### How It Works
+
+```
+User Query → Local Embedding Model → Vector Search → Ranked Results
+                    ↑                         ↓
+              Runs on CPU              LanceDB Index
+            (no GPU required)         (embedded database)
+```
+
+When you call `memory_load`, MemHub:
+1. Converts your query to a vector using a local quantized model
+2. Searches the LanceDB index for semantically similar memories
+3. Returns ranked results with relevance scores
+
+This means "testing framework preference" finds memories about "Vitest vs Jest decision" — even without exact keyword matches.
+
+---
+
+## Features
+
+- **Semantic Search** — Vector-based similarity search with LanceDB
+- **Local Embeddings** — Quantized Transformers.js model, runs on CPU
+- **Markdown Storage** — Human-readable `.md` files with YAML front matter
+- **Git-Friendly** — Version control, diff, review your memories
+- **MCP Protocol** — Works with Claude Code, Cursor, Cline, Windsurf, and more
+- **One-Line Setup** — `npx -y @synth-coder/memhub@latest init`
+
+---
+
+## Environment Variables
+
+- `MEMHUB_STORAGE_PATH` (default: `~/.memhub`)
+- `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
+
+---
+
+## Memory File Format
+
+```markdown
+---
+id: "550e8400-e29b-41d4-a716-446655440000"
+created_at: "2026-03-03T08:00:00.000Z"
+updated_at: "2026-03-03T08:00:00.000Z"
+tags:
+  - architecture
+  - tdd
+category: "engineering"
+importance: 4
+---
+
+# Contract-first MCP design
+
+Define tool contracts and schemas before implementation.
+```
+
+Filename format:
+
+```text
+YYYY-MM-DD-title-slug.md
+```
+
+---
+
+## Development
+
+### Install & Build
+
+```bash
+npx pnpm install
+npx pnpm run build
+```
+
+### Scripts
+
+```bash
+npx pnpm run build
+npx pnpm run lint
+npx pnpm run format
+npx pnpm run typecheck
+npx pnpm run test
+npx pnpm run quality
+```
+
+### Engineering Workflow
+
+- Contract-first (types + schema first)
+- TDD (`red -> green -> refactor`)
+- Quality gate enforced before merge
+- Coverage threshold: **>= 80%**
+
+---
+
+## Project Structure
+
+```text
+memhub/
+├── docs/
+├── src/
+│   ├── contracts/
+│   ├── server/
+│   ├── services/
+│   ├── storage/
+│   └── utils/
+├── test/
+└── .github/workflows/
+```
+
+---
+
+## Roadmap
+
+- [x] Architecture and contracts
+- [x] Core storage/service/server implementation
+- [x] Quality gate (lint/typecheck/test/coverage)
+- [x] CLI init command for quick setup
+- [ ] Integration tests
+- [ ] Performance improvements
+- [x] npm release (`@synth-coder/memhub@0.2.5`)
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -8,48 +8,99 @@ MemHub 将“用户决策、长期偏好、可复用知识”保存为 **Markdow
 
 ## 为什么用 MemHub
 
-- **Git 原生**：所有记忆都是纯文本文件，天然可 diff / 可回滚
-- **面向 Agent**：通过 MCP（stdio）暴露工具，便于模型调用
-- **人类可读**：元数据在 YAML，正文在 Markdown
-- **质量可控**：内置 lint / typecheck / test / coverage 门禁
+大多数 AI 记忆工具依赖外部 API 或简单的关键词匹配。MemHub 不同：
+
+### 本地 AI 语义搜索
+
+- **向量数据库**：基于 LanceDB 实现快速相似度搜索
+- **本地嵌入模型**：量化版 Transformers.js 模型，完全在本地运行
+- **零 API 成本**：无需外部服务、无需 API 密钥、无速率限制
+- **隐私优先**：你的记忆永远不会离开你的电脑
+
+### Git 原生存储
+
+- **纯文本格式**：所有记忆都是带 YAML front matter 的 Markdown 文件
+- **版本控制**：像代码一样提交、分支、审查、回滚
+- **人类可读**：用任何文本编辑器浏览和编辑记忆
+- **团队友好**：通过 git 仓库共享记忆
+
+### 工作原理
+
+```
+用户查询 → 本地嵌入模型 → 向量搜索 → 排序结果
+              ↑                    ↓
+        运行在 CPU           LanceDB 索引
+       (无需 GPU)           (嵌入式数据库)
+```
+
+当你调用 `memory_load` 时，MemHub：
+1. 使用本地量化模型将查询转换为向量
+2. 在 LanceDB 索引中搜索语义相似的记忆
+3. 返回带有相关性分数的排序结果
+
+这意味着"测试框架偏好"可以找到关于"Vitest vs Jest 决策"的记忆——即使没有精确的关键词匹配。
 
 ---
 
 ## 核心特性
 
-- Markdown 持久化（`.md`）
-- YAML Front Matter 元数据（`id / session_id / entry_type / tags / category / importance / 时间戳`）
-- STM-first 双工具接口：`memory_load` + `memory_update`
-- 并发 CLI 安全目录：`YYYY-MM-DD/session_uuid/...`
-- MCP stdio server，可接入主流 MCP 客户端
+- **语义搜索** — 基于 LanceDB 的向量相似度搜索
+- **本地嵌入** — 量化版 Transformers.js 模型，CPU 运行
+- **Markdown 存储** — 人类可读的 `.md` 文件，带 YAML front matter
+- **Git 友好** — 版本控制、diff、审查你的记忆
+- **MCP 协议** — 支持 Claude Code、Cursor、Cline、Windsurf 等
+- **一键配置** — `npx -y @synth-coder/memhub@latest init`
 
 ---
 
 ## 快速开始
 
-### 1）从 npm 安装
+### 一键配置
+
+使用一条命令为你的 AI 代理配置 MemHub：
 
 ```bash
-npm i @synth-coder/memhub
+npx -y @synth-coder/memhub@latest init
 ```
 
-### 2）本地开发安装依赖
+这将启动交互式提示选择你的代理。MemHub 会：
+1. 将 MCP 服务器配置添加到代理的配置文件
+2. 将 MemHub 使用说明添加到代理的规则文件
 
-```bash
-npm install
-```
+**支持的代理：**
 
-### 3）构建
+| 代理 | 配置文件 | 指令文件 |
+|------|----------|----------|
+| Claude Code | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursorrules` |
+| Cline | `~/.cline/mcp.json` | `~/.clinerules` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.windsurfrules` |
+| Factory Droid | `~/.factory/mcp.json` | `~/.factory/AGENTS.md` |
+| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` |
+| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
 
-```bash
-npm run build
-```
+### CLI 选项
 
-### 4）执行质量门禁
 ```bash
-npm run quality
+# 交互式选择（全局 - 默认）
+npx -y @synth-coder/memhub@latest init
+
+# 跳过交互式提示
+npx -y @synth-coder/memhub@latest init -a claude-code
+
+# 仅配置当前项目（本地）
+npx -y @synth-coder/memhub@latest init -a cursor -l
+
+# 更新现有配置
+npx -y @synth-coder/memhub@latest init -a claude-code --force
 ```
 
+| 选项 | 说明 |
+|------|------|
+| `-a, --agent <名称>` | 代理类型（跳过交互式选择） |
+| `-l, --local` | 配置当前项目（默认：全局） |
+| `-f, --force` | 更新现有配置 |
+
 ---
 
 ## 作为 MCP Server 使用（stdio）
@@ -57,30 +108,38 @@ npm run quality
 ### 方式 A：npx 直接运行（推荐）
 
 ```bash
-npx -y @synth-coder/memhub
+npx -y @synth-coder/memhub@latest
 ```
 
 > Windows 下不要在包名后再加 `memhub` 参数。
 > 如果出现“弹出源码 .js 文件”的情况，请升级到最新版本（`0.1.2+`）后重试。
 
-在你的 MCP 客户端配置中添加：
+在你的 MCP 客户端配置中添加：
 
 ```json
 {
   "mcpServers": {
     "memhub": {
       "command": "npx",
-      "args": ["-y", "@synth-coder/memhub"],
+      "args": ["-y", "@synth-coder/memhub@latest"],
       "env": {
         "MEMHUB_STORAGE_PATH": "/绝对路径/你的记忆目录",
         "MEMHUB_LOG_LEVEL": "info"
       }
     }
   }
-}
-```
-
-### 方式 B：本地仓库运行
+}
+```
+
+如果是 Codex（`~/.codex/config.toml`），请使用 TOML 键 `mcp_servers`：
+
+```toml
+[mcp_servers.memhub]
+command = "npx"
+args = ["-y", "@synth-coder/memhub@latest"]
+```
+
+### 方式 B：本地仓库运行
 
 ```json
 {
@@ -131,7 +190,7 @@ YYYY-MM-DD-title-slug.md
 
 ## MCP 工具列表
 
-> 调用策略建议见：`docs/tool-calling-policy.md`（首轮 `memory_load`，末轮 `memory_update`）。
+> 详见 [docs/mcp-tools.md](docs/mcp-tools.md) 获取 API 参考。
 
 - `memory_load`：首轮加载短期记忆（STM）上下文
 - `memory_update`：末轮回写决策/偏好/知识/状态变化
@@ -182,9 +241,10 @@ memhub/
 - [x] 架构与契约设计
 - [x] 核心实现（storage/service/server）
 - [x] 质量门禁（lint/typecheck/test/coverage）
+- [x] CLI init 命令快速配置
 - [ ] 集成测试
 - [ ] 性能优化
-- [x] npm 发布（`@synth-coder/memhub@0.1.3`）
+- [x] npm 发布（`@synth-coder/memhub@0.2.5`）
 
 ---
 

package/dist/src/cli/agents/claude-code.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Claude Code MCP configuration generator
+ */
+export declare function generateClaudeCodeConfig(_memhubPath: string): Record<string, unknown>;
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/src/cli/agents/claude-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../../src/cli/agents/claude-code.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASrF"}