@synth-coder/memhub 0.2.5 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.eslintrc.cjs +45 -45
- package/.factory/commands/opsx-apply.md +150 -150
- package/.factory/commands/opsx-archive.md +155 -155
- package/.factory/commands/opsx-explore.md +171 -171
- package/.factory/commands/opsx-propose.md +104 -104
- package/.factory/skills/openspec-apply-change/SKILL.md +156 -156
- package/.factory/skills/openspec-archive-change/SKILL.md +114 -114
- package/.factory/skills/openspec-explore/SKILL.md +288 -288
- package/.factory/skills/openspec-propose/SKILL.md +110 -110
- package/.github/workflows/ci.yml +110 -110
- package/.iflow/commands/opsx-apply.md +152 -152
- package/.iflow/commands/opsx-archive.md +157 -157
- package/.iflow/commands/opsx-explore.md +173 -173
- package/.iflow/commands/opsx-propose.md +106 -106
- package/.iflow/skills/openspec-apply-change/SKILL.md +156 -156
- package/.iflow/skills/openspec-archive-change/SKILL.md +114 -114
- package/.iflow/skills/openspec-explore/SKILL.md +288 -288
- package/.iflow/skills/openspec-propose/SKILL.md +110 -110
- package/.prettierrc +11 -11
- package/AGENTS.md +167 -167
- package/README.md +1 -1
- package/README.zh-CN.md +240 -240
- package/dist/src/cli/agents/claude-code.js +1 -1
- package/dist/src/cli/agents/claude-code.js.map +1 -1
- package/dist/src/cli/agents/cline.js +1 -1
- package/dist/src/cli/agents/cline.js.map +1 -1
- package/dist/src/cli/agents/codex.d.ts +5 -0
- package/dist/src/cli/agents/codex.d.ts.map +1 -0
- package/dist/src/cli/agents/codex.js +14 -0
- package/dist/src/cli/agents/codex.js.map +1 -0
- package/dist/src/cli/agents/cursor.js +1 -1
- package/dist/src/cli/agents/cursor.js.map +1 -1
- package/dist/src/cli/agents/factory-droid.js +1 -1
- package/dist/src/cli/agents/factory-droid.js.map +1 -1
- package/dist/src/cli/agents/gemini-cli.js +1 -1
- package/dist/src/cli/agents/gemini-cli.js.map +1 -1
- package/dist/src/cli/agents/index.d.ts +1 -0
- package/dist/src/cli/agents/index.d.ts.map +1 -1
- package/dist/src/cli/agents/index.js +3 -0
- package/dist/src/cli/agents/index.js.map +1 -1
- package/dist/src/cli/agents/windsurf.js +1 -1
- package/dist/src/cli/agents/windsurf.js.map +1 -1
- package/dist/src/cli/index.js +0 -0
- package/dist/src/cli/init.d.ts.map +1 -1
- package/dist/src/cli/init.js +36 -15
- package/dist/src/cli/init.js.map +1 -1
- package/dist/src/cli/types.d.ts +2 -2
- package/dist/src/cli/types.d.ts.map +1 -1
- package/dist/src/cli/types.js +11 -0
- package/dist/src/cli/types.js.map +1 -1
- package/package.json +16 -16
- package/tsconfig.json +25 -25
- package/tsconfig.test.json +8 -8
- package/vitest.config.ts +29 -29
package/README.zh-CN.md
CHANGED
|
@@ -1,133 +1,133 @@
|
|
|
1
|
-
# MemHub
|
|
2
|
-
|
|
3
|
-
一个面向编码代理(Codex / Claude Code / OpenCode 等)的 **Git 友好记忆 MCP Server**。
|
|
4
|
-
|
|
5
|
-
MemHub 将“用户决策、长期偏好、可复用知识”保存为 **Markdown 文件 + YAML Front Matter**,便于人读、审查、版本管理和协作。
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 为什么用 MemHub
|
|
10
|
-
|
|
11
|
-
大多数 AI 记忆工具依赖外部 API 或简单的关键词匹配。MemHub 不同:
|
|
12
|
-
|
|
13
|
-
### 本地 AI 语义搜索
|
|
14
|
-
|
|
15
|
-
- **向量数据库**:基于 LanceDB 实现快速相似度搜索
|
|
16
|
-
- **本地嵌入模型**:量化版 Transformers.js 模型,完全在本地运行
|
|
17
|
-
- **零 API 成本**:无需外部服务、无需 API 密钥、无速率限制
|
|
18
|
-
- **隐私优先**:你的记忆永远不会离开你的电脑
|
|
19
|
-
|
|
20
|
-
### Git 原生存储
|
|
21
|
-
|
|
22
|
-
- **纯文本格式**:所有记忆都是带 YAML front matter 的 Markdown 文件
|
|
23
|
-
- **版本控制**:像代码一样提交、分支、审查、回滚
|
|
24
|
-
- **人类可读**:用任何文本编辑器浏览和编辑记忆
|
|
25
|
-
- **团队友好**:通过 git 仓库共享记忆
|
|
26
|
-
|
|
27
|
-
### 工作原理
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
用户查询 → 本地嵌入模型 → 向量搜索 → 排序结果
|
|
31
|
-
↑ ↓
|
|
32
|
-
运行在 CPU LanceDB 索引
|
|
33
|
-
(无需 GPU) (嵌入式数据库)
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
当你调用 `memory_load` 时,MemHub:
|
|
37
|
-
1. 使用本地量化模型将查询转换为向量
|
|
38
|
-
2. 在 LanceDB 索引中搜索语义相似的记忆
|
|
39
|
-
3. 返回带有相关性分数的排序结果
|
|
40
|
-
|
|
41
|
-
这意味着"测试框架偏好"可以找到关于"Vitest vs Jest 决策"的记忆——即使没有精确的关键词匹配。
|
|
42
|
-
|
|
43
|
-
---
|
|
44
|
-
|
|
45
|
-
## 核心特性
|
|
46
|
-
|
|
47
|
-
- **语义搜索** — 基于 LanceDB 的向量相似度搜索
|
|
48
|
-
- **本地嵌入** — 量化版 Transformers.js 模型,CPU 运行
|
|
49
|
-
- **Markdown 存储** — 人类可读的 `.md` 文件,带 YAML front matter
|
|
50
|
-
- **Git 友好** — 版本控制、diff、审查你的记忆
|
|
51
|
-
- **MCP 协议** — 支持 Claude Code、Cursor、Cline、Windsurf 等
|
|
52
|
-
- **一键配置** — `npx -y @synth-coder/memhub@latest init`
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## 快速开始
|
|
57
|
-
|
|
58
|
-
### 一键配置
|
|
59
|
-
|
|
60
|
-
使用一条命令为你的 AI 代理配置 MemHub:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
npx -y @synth-coder/memhub@latest init
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
这将启动交互式提示选择你的代理。MemHub 会:
|
|
67
|
-
1. 将 MCP 服务器配置添加到代理的配置文件
|
|
68
|
-
2. 将 MemHub 使用说明添加到代理的规则文件
|
|
69
|
-
|
|
70
|
-
**支持的代理:**
|
|
71
|
-
|
|
72
|
-
| 代理 | 配置文件 | 指令文件 |
|
|
73
|
-
|------|----------|----------|
|
|
74
|
-
| Claude Code | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
|
|
75
|
-
| Cursor | `~/.cursor/mcp.json` | `~/.cursorrules` |
|
|
76
|
-
| Cline | `~/.cline/mcp.json` | `~/.clinerules` |
|
|
77
|
-
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.windsurfrules` |
|
|
78
|
-
| Factory Droid | `~/.factory/mcp.json` | `~/.factory/AGENTS.md` |
|
|
79
|
-
| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` |
|
|
80
|
-
| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
|
|
81
|
-
|
|
82
|
-
### CLI 选项
|
|
83
|
-
|
|
84
|
-
```bash
|
|
85
|
-
# 交互式选择(全局 - 默认)
|
|
86
|
-
npx -y @synth-coder/memhub@latest init
|
|
87
|
-
|
|
88
|
-
# 跳过交互式提示
|
|
89
|
-
npx -y @synth-coder/memhub@latest init -a claude-code
|
|
90
|
-
|
|
91
|
-
# 仅配置当前项目(本地)
|
|
92
|
-
npx -y @synth-coder/memhub@latest init -a cursor -l
|
|
93
|
-
|
|
94
|
-
# 更新现有配置
|
|
95
|
-
npx -y @synth-coder/memhub@latest init -a claude-code --force
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
| 选项 | 说明 |
|
|
99
|
-
|------|------|
|
|
100
|
-
| `-a, --agent <名称>` | 代理类型(跳过交互式选择) |
|
|
101
|
-
| `-l, --local` | 配置当前项目(默认:全局) |
|
|
102
|
-
| `-f, --force` | 更新现有配置 |
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
## 作为 MCP Server 使用(stdio)
|
|
107
|
-
|
|
108
|
-
### 方式 A:npx 直接运行(推荐)
|
|
109
|
-
|
|
110
|
-
```bash
|
|
111
|
-
npx -y @synth-coder/memhub@latest
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
> Windows 下不要在包名后再加 `memhub` 参数。
|
|
115
|
-
> 如果出现“弹出源码 .js 文件”的情况,请升级到最新版本(`0.1.2+`)后重试。
|
|
116
|
-
|
|
1
|
+
# MemHub
|
|
2
|
+
|
|
3
|
+
一个面向编码代理(Codex / Claude Code / OpenCode 等)的 **Git 友好记忆 MCP Server**。
|
|
4
|
+
|
|
5
|
+
MemHub 将“用户决策、长期偏好、可复用知识”保存为 **Markdown 文件 + YAML Front Matter**,便于人读、审查、版本管理和协作。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 为什么用 MemHub
|
|
10
|
+
|
|
11
|
+
大多数 AI 记忆工具依赖外部 API 或简单的关键词匹配。MemHub 不同:
|
|
12
|
+
|
|
13
|
+
### 本地 AI 语义搜索
|
|
14
|
+
|
|
15
|
+
- **向量数据库**:基于 LanceDB 实现快速相似度搜索
|
|
16
|
+
- **本地嵌入模型**:量化版 Transformers.js 模型,完全在本地运行
|
|
17
|
+
- **零 API 成本**:无需外部服务、无需 API 密钥、无速率限制
|
|
18
|
+
- **隐私优先**:你的记忆永远不会离开你的电脑
|
|
19
|
+
|
|
20
|
+
### Git 原生存储
|
|
21
|
+
|
|
22
|
+
- **纯文本格式**:所有记忆都是带 YAML front matter 的 Markdown 文件
|
|
23
|
+
- **版本控制**:像代码一样提交、分支、审查、回滚
|
|
24
|
+
- **人类可读**:用任何文本编辑器浏览和编辑记忆
|
|
25
|
+
- **团队友好**:通过 git 仓库共享记忆
|
|
26
|
+
|
|
27
|
+
### 工作原理
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
用户查询 → 本地嵌入模型 → 向量搜索 → 排序结果
|
|
31
|
+
↑ ↓
|
|
32
|
+
运行在 CPU LanceDB 索引
|
|
33
|
+
(无需 GPU) (嵌入式数据库)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
当你调用 `memory_load` 时,MemHub:
|
|
37
|
+
1. 使用本地量化模型将查询转换为向量
|
|
38
|
+
2. 在 LanceDB 索引中搜索语义相似的记忆
|
|
39
|
+
3. 返回带有相关性分数的排序结果
|
|
40
|
+
|
|
41
|
+
这意味着"测试框架偏好"可以找到关于"Vitest vs Jest 决策"的记忆——即使没有精确的关键词匹配。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 核心特性
|
|
46
|
+
|
|
47
|
+
- **语义搜索** — 基于 LanceDB 的向量相似度搜索
|
|
48
|
+
- **本地嵌入** — 量化版 Transformers.js 模型,CPU 运行
|
|
49
|
+
- **Markdown 存储** — 人类可读的 `.md` 文件,带 YAML front matter
|
|
50
|
+
- **Git 友好** — 版本控制、diff、审查你的记忆
|
|
51
|
+
- **MCP 协议** — 支持 Claude Code、Cursor、Cline、Windsurf 等
|
|
52
|
+
- **一键配置** — `npx -y @synth-coder/memhub@latest init`
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 快速开始
|
|
57
|
+
|
|
58
|
+
### 一键配置
|
|
59
|
+
|
|
60
|
+
使用一条命令为你的 AI 代理配置 MemHub:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npx -y @synth-coder/memhub@latest init
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
这将启动交互式提示选择你的代理。MemHub 会:
|
|
67
|
+
1. 将 MCP 服务器配置添加到代理的配置文件
|
|
68
|
+
2. 将 MemHub 使用说明添加到代理的规则文件
|
|
69
|
+
|
|
70
|
+
**支持的代理:**
|
|
71
|
+
|
|
72
|
+
| 代理 | 配置文件 | 指令文件 |
|
|
73
|
+
|------|----------|----------|
|
|
74
|
+
| Claude Code | `~/.claude/settings.json` | `~/.claude/CLAUDE.md` |
|
|
75
|
+
| Cursor | `~/.cursor/mcp.json` | `~/.cursorrules` |
|
|
76
|
+
| Cline | `~/.cline/mcp.json` | `~/.clinerules` |
|
|
77
|
+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.windsurfrules` |
|
|
78
|
+
| Factory Droid | `~/.factory/mcp.json` | `~/.factory/AGENTS.md` |
|
|
79
|
+
| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` |
|
|
80
|
+
| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` |
|
|
81
|
+
|
|
82
|
+
### CLI 选项
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# 交互式选择(全局 - 默认)
|
|
86
|
+
npx -y @synth-coder/memhub@latest init
|
|
87
|
+
|
|
88
|
+
# 跳过交互式提示
|
|
89
|
+
npx -y @synth-coder/memhub@latest init -a claude-code
|
|
90
|
+
|
|
91
|
+
# 仅配置当前项目(本地)
|
|
92
|
+
npx -y @synth-coder/memhub@latest init -a cursor -l
|
|
93
|
+
|
|
94
|
+
# 更新现有配置
|
|
95
|
+
npx -y @synth-coder/memhub@latest init -a claude-code --force
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
| 选项 | 说明 |
|
|
99
|
+
|------|------|
|
|
100
|
+
| `-a, --agent <名称>` | 代理类型(跳过交互式选择) |
|
|
101
|
+
| `-l, --local` | 配置当前项目(默认:全局) |
|
|
102
|
+
| `-f, --force` | 更新现有配置 |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 作为 MCP Server 使用(stdio)
|
|
107
|
+
|
|
108
|
+
### 方式 A:npx 直接运行(推荐)
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npx -y @synth-coder/memhub@latest
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
> Windows 下不要在包名后再加 `memhub` 参数。
|
|
115
|
+
> 如果出现“弹出源码 .js 文件”的情况,请升级到最新版本(`0.1.2+`)后重试。
|
|
116
|
+
|
|
117
117
|
在你的 MCP 客户端配置中添加:
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"memhub": {
|
|
123
|
-
"command": "npx",
|
|
124
|
-
"args": ["-y", "@synth-coder/memhub@latest"],
|
|
125
|
-
"env": {
|
|
126
|
-
"MEMHUB_STORAGE_PATH": "/绝对路径/你的记忆目录",
|
|
127
|
-
"MEMHUB_LOG_LEVEL": "info"
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
}
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"mcpServers": {
|
|
122
|
+
"memhub": {
|
|
123
|
+
"command": "npx",
|
|
124
|
+
"args": ["-y", "@synth-coder/memhub@latest"],
|
|
125
|
+
"env": {
|
|
126
|
+
"MEMHUB_STORAGE_PATH": "/绝对路径/你的记忆目录",
|
|
127
|
+
"MEMHUB_LOG_LEVEL": "info"
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
131
|
}
|
|
132
132
|
```
|
|
133
133
|
|
|
@@ -140,114 +140,114 @@ args = ["-y", "@synth-coder/memhub@latest"]
|
|
|
140
140
|
```
|
|
141
141
|
|
|
142
142
|
### 方式 B:本地仓库运行
|
|
143
|
-
|
|
144
|
-
```json
|
|
145
|
-
{
|
|
146
|
-
"mcpServers": {
|
|
147
|
-
"memhub": {
|
|
148
|
-
"command": "node",
|
|
149
|
-
"args": ["dist/src/server/mcp-server.js"]
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
---
|
|
156
|
-
|
|
157
|
-
## 环境变量
|
|
158
|
-
|
|
159
|
-
- `MEMHUB_STORAGE_PATH`:记忆存储目录(默认:`./memories`)
|
|
160
|
-
- `MEMHUB_LOG_LEVEL`:日志级别(默认:`info`,可选:`debug|info|warn|error`)
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## 记忆文件格式
|
|
165
|
-
|
|
166
|
-
```markdown
|
|
167
|
-
---
|
|
168
|
-
id: "550e8400-e29b-41d4-a716-446655440000"
|
|
169
|
-
created_at: "2026-03-03T08:00:00.000Z"
|
|
170
|
-
updated_at: "2026-03-03T08:00:00.000Z"
|
|
171
|
-
tags:
|
|
172
|
-
- architecture
|
|
173
|
-
- tdd
|
|
174
|
-
category: "engineering"
|
|
175
|
-
importance: 4
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
# Contract-first MCP 设计
|
|
179
|
-
|
|
180
|
-
先定义工具契约与 schema,再进入实现。
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
文件名格式:
|
|
184
|
-
|
|
185
|
-
```text
|
|
186
|
-
YYYY-MM-DD-title-slug.md
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## MCP 工具列表
|
|
192
|
-
|
|
193
|
-
> 详见 [docs/mcp-tools.md](docs/mcp-tools.md) 获取 API 参考。
|
|
194
|
-
|
|
195
|
-
- `memory_load`:首轮加载短期记忆(STM)上下文
|
|
196
|
-
- `memory_update`:末轮回写决策/偏好/知识/状态变化
|
|
197
|
-
|
|
198
|
-
---
|
|
199
|
-
|
|
200
|
-
## 开发说明
|
|
201
|
-
|
|
202
|
-
### 常用脚本
|
|
203
|
-
|
|
204
|
-
```bash
|
|
205
|
-
npm run build
|
|
206
|
-
npm run lint
|
|
207
|
-
npm run typecheck
|
|
208
|
-
npm run test
|
|
209
|
-
npm run test:coverage
|
|
210
|
-
npm run quality
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
### 工程流程(默认)
|
|
214
|
-
|
|
215
|
-
- 契约优先(先类型与 schema)
|
|
216
|
-
- 严格 TDD(`红 -> 绿 -> 重构`)
|
|
217
|
-
- 合并前必须通过质量门禁
|
|
218
|
-
- 覆盖率阈值:**>= 80%**
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
## 项目结构
|
|
223
|
-
|
|
224
|
-
```text
|
|
225
|
-
memhub/
|
|
226
|
-
├── docs/
|
|
227
|
-
├── src/
|
|
228
|
-
│ ├── contracts/
|
|
229
|
-
│ ├── server/
|
|
230
|
-
│ ├── services/
|
|
231
|
-
│ ├── storage/
|
|
232
|
-
│ └── utils/
|
|
233
|
-
├── test/
|
|
234
|
-
└── .github/workflows/
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
---
|
|
238
|
-
|
|
239
|
-
## 路线图
|
|
240
|
-
|
|
241
|
-
- [x] 架构与契约设计
|
|
242
|
-
- [x] 核心实现(storage/service/server)
|
|
243
|
-
- [x] 质量门禁(lint/typecheck/test/coverage)
|
|
244
|
-
- [x] CLI init 命令快速配置
|
|
245
|
-
- [ ] 集成测试
|
|
246
|
-
- [ ] 性能优化
|
|
247
|
-
- [x] npm 发布(`@synth-coder/memhub@0.2.
|
|
248
|
-
|
|
249
|
-
---
|
|
250
|
-
|
|
251
|
-
## License
|
|
252
|
-
|
|
253
|
-
MIT
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"mcpServers": {
|
|
147
|
+
"memhub": {
|
|
148
|
+
"command": "node",
|
|
149
|
+
"args": ["dist/src/server/mcp-server.js"]
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 环境变量
|
|
158
|
+
|
|
159
|
+
- `MEMHUB_STORAGE_PATH`:记忆存储目录(默认:`./memories`)
|
|
160
|
+
- `MEMHUB_LOG_LEVEL`:日志级别(默认:`info`,可选:`debug|info|warn|error`)
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
## 记忆文件格式
|
|
165
|
+
|
|
166
|
+
```markdown
|
|
167
|
+
---
|
|
168
|
+
id: "550e8400-e29b-41d4-a716-446655440000"
|
|
169
|
+
created_at: "2026-03-03T08:00:00.000Z"
|
|
170
|
+
updated_at: "2026-03-03T08:00:00.000Z"
|
|
171
|
+
tags:
|
|
172
|
+
- architecture
|
|
173
|
+
- tdd
|
|
174
|
+
category: "engineering"
|
|
175
|
+
importance: 4
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
# Contract-first MCP 设计
|
|
179
|
+
|
|
180
|
+
先定义工具契约与 schema,再进入实现。
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
文件名格式:
|
|
184
|
+
|
|
185
|
+
```text
|
|
186
|
+
YYYY-MM-DD-title-slug.md
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## MCP 工具列表
|
|
192
|
+
|
|
193
|
+
> 详见 [docs/mcp-tools.md](docs/mcp-tools.md) 获取 API 参考。
|
|
194
|
+
|
|
195
|
+
- `memory_load`:首轮加载短期记忆(STM)上下文
|
|
196
|
+
- `memory_update`:末轮回写决策/偏好/知识/状态变化
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 开发说明
|
|
201
|
+
|
|
202
|
+
### 常用脚本
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
npm run build
|
|
206
|
+
npm run lint
|
|
207
|
+
npm run typecheck
|
|
208
|
+
npm run test
|
|
209
|
+
npm run test:coverage
|
|
210
|
+
npm run quality
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### 工程流程(默认)
|
|
214
|
+
|
|
215
|
+
- 契约优先(先类型与 schema)
|
|
216
|
+
- 严格 TDD(`红 -> 绿 -> 重构`)
|
|
217
|
+
- 合并前必须通过质量门禁
|
|
218
|
+
- 覆盖率阈值:**>= 80%**
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 项目结构
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
memhub/
|
|
226
|
+
├── docs/
|
|
227
|
+
├── src/
|
|
228
|
+
│ ├── contracts/
|
|
229
|
+
│ ├── server/
|
|
230
|
+
│ ├── services/
|
|
231
|
+
│ ├── storage/
|
|
232
|
+
│ └── utils/
|
|
233
|
+
├── test/
|
|
234
|
+
└── .github/workflows/
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 路线图
|
|
240
|
+
|
|
241
|
+
- [x] 架构与契约设计
|
|
242
|
+
- [x] 核心实现(storage/service/server)
|
|
243
|
+
- [x] 质量门禁(lint/typecheck/test/coverage)
|
|
244
|
+
- [x] CLI init 命令快速配置
|
|
245
|
+
- [ ] 集成测试
|
|
246
|
+
- [ ] 性能优化
|
|
247
|
+
- [x] npm 发布(`@synth-coder/memhub@0.2.6`)
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## License
|
|
252
|
+
|
|
253
|
+
MIT
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../../../src/cli/agents/claude-code.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"claude-code.js","sourceRoot":"","sources":["../../../../src/cli/agents/claude-code.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cline.js","sourceRoot":"","sources":["../../../../src/cli/agents/cline.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"cline.js","sourceRoot":"","sources":["../../../../src/cli/agents/cline.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../../../src/cli/agents/codex.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAShF"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Codex MCP configuration generator
|
|
3
|
+
*/
|
|
4
|
+
export function generateCodexConfig(_memhubPath) {
|
|
5
|
+
return {
|
|
6
|
+
mcp_servers: {
|
|
7
|
+
memhub: {
|
|
8
|
+
command: 'npx',
|
|
9
|
+
args: ['-y', '@synth-coder/memhub@latest'],
|
|
10
|
+
},
|
|
11
|
+
},
|
|
12
|
+
};
|
|
13
|
+
}
|
|
14
|
+
//# sourceMappingURL=codex.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codex.js","sourceRoot":"","sources":["../../../../src/cli/agents/codex.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO;QACL,WAAW,EAAE;YACX,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../../src/cli/agents/cursor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../../src/cli/agents/cursor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"factory-droid.js","sourceRoot":"","sources":["../../../../src/cli/agents/factory-droid.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,0BAA0B,CAAC,WAAmB;IAC5D,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"factory-droid.js","sourceRoot":"","sources":["../../../../src/cli/agents/factory-droid.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,0BAA0B,CAAC,WAAmB;IAC5D,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gemini-cli.js","sourceRoot":"","sources":["../../../../src/cli/agents/gemini-cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"gemini-cli.js","sourceRoot":"","sources":["../../../../src/cli/agents/gemini-cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -7,6 +7,7 @@ export { generateClineConfig } from './cline.js';
|
|
|
7
7
|
export { generateWindsurfConfig } from './windsurf.js';
|
|
8
8
|
export { generateFactoryDroidConfig } from './factory-droid.js';
|
|
9
9
|
export { generateGeminiCliConfig } from './gemini-cli.js';
|
|
10
|
+
export { generateCodexConfig } from './codex.js';
|
|
10
11
|
import type { AgentType } from '../types.js';
|
|
11
12
|
export type ConfigGenerator = (memhubPath: string) => Record<string, unknown>;
|
|
12
13
|
export declare function getConfigGenerator(agentId: AgentType): ConfigGenerator;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/agents/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/agents/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C,MAAM,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAY9E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,GAAG,eAAe,CAEtE"}
|
|
@@ -7,12 +7,14 @@ export { generateClineConfig } from './cline.js';
|
|
|
7
7
|
export { generateWindsurfConfig } from './windsurf.js';
|
|
8
8
|
export { generateFactoryDroidConfig } from './factory-droid.js';
|
|
9
9
|
export { generateGeminiCliConfig } from './gemini-cli.js';
|
|
10
|
+
export { generateCodexConfig } from './codex.js';
|
|
10
11
|
import { generateCursorConfig } from './cursor.js';
|
|
11
12
|
import { generateClaudeCodeConfig } from './claude-code.js';
|
|
12
13
|
import { generateClineConfig } from './cline.js';
|
|
13
14
|
import { generateWindsurfConfig } from './windsurf.js';
|
|
14
15
|
import { generateFactoryDroidConfig } from './factory-droid.js';
|
|
15
16
|
import { generateGeminiCliConfig } from './gemini-cli.js';
|
|
17
|
+
import { generateCodexConfig } from './codex.js';
|
|
16
18
|
const generators = {
|
|
17
19
|
cursor: generateCursorConfig,
|
|
18
20
|
'claude-code': generateClaudeCodeConfig,
|
|
@@ -20,6 +22,7 @@ const generators = {
|
|
|
20
22
|
windsurf: generateWindsurfConfig,
|
|
21
23
|
'factory-droid': generateFactoryDroidConfig,
|
|
22
24
|
'gemini-cli': generateGeminiCliConfig,
|
|
25
|
+
codex: generateCodexConfig,
|
|
23
26
|
};
|
|
24
27
|
export function getConfigGenerator(agentId) {
|
|
25
28
|
return generators[agentId];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cli/agents/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cli/agents/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,UAAU,GAAuC;IACrD,MAAM,EAAE,oBAAoB;IAC5B,aAAa,EAAE,wBAAwB;IACvC,KAAK,EAAE,mBAAmB;IAC1B,QAAQ,EAAE,sBAAsB;IAChC,eAAe,EAAE,0BAA0B;IAC3C,YAAY,EAAE,uBAAuB;IACrC,KAAK,EAAE,mBAAmB;CAC3B,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,OAAkB;IACnD,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"windsurf.js","sourceRoot":"","sources":["../../../../src/cli/agents/windsurf.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"windsurf.js","sourceRoot":"","sources":["../../../../src/cli/agents/windsurf.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO;QACL,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,OAAO,EAAE,KAAK;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,4BAA4B,CAAC;aAC3C;SACF;KACF,CAAC;AACJ,CAAC"}
|
package/dist/src/cli/index.js
CHANGED
|
File without changes
|