@synth-coder/memhub 0.1.0
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 +46 -0
- package/.github/workflows/ci.yml +74 -0
- package/.iflow/commands/opsx-apply.md +152 -0
- package/.iflow/commands/opsx-archive.md +157 -0
- package/.iflow/commands/opsx-explore.md +173 -0
- package/.iflow/commands/opsx-propose.md +106 -0
- package/.iflow/skills/openspec-apply-change/SKILL.md +156 -0
- package/.iflow/skills/openspec-archive-change/SKILL.md +114 -0
- package/.iflow/skills/openspec-explore/SKILL.md +288 -0
- package/.iflow/skills/openspec-propose/SKILL.md +110 -0
- package/.prettierrc +11 -0
- package/README.md +171 -0
- package/README.zh-CN.md +169 -0
- package/dist/src/contracts/index.d.ts +7 -0
- package/dist/src/contracts/index.d.ts.map +1 -0
- package/dist/src/contracts/index.js +10 -0
- package/dist/src/contracts/index.js.map +1 -0
- package/dist/src/contracts/mcp.d.ts +194 -0
- package/dist/src/contracts/mcp.d.ts.map +1 -0
- package/dist/src/contracts/mcp.js +112 -0
- package/dist/src/contracts/mcp.js.map +1 -0
- package/dist/src/contracts/schemas.d.ts +1153 -0
- package/dist/src/contracts/schemas.d.ts.map +1 -0
- package/dist/src/contracts/schemas.js +246 -0
- package/dist/src/contracts/schemas.js.map +1 -0
- package/dist/src/contracts/types.d.ts +328 -0
- package/dist/src/contracts/types.d.ts.map +1 -0
- package/dist/src/contracts/types.js +30 -0
- package/dist/src/contracts/types.js.map +1 -0
- package/dist/src/index.d.ts +8 -0
- package/dist/src/index.d.ts.map +1 -0
- package/dist/src/index.js +8 -0
- package/dist/src/index.js.map +1 -0
- package/dist/src/server/index.d.ts +5 -0
- package/dist/src/server/index.d.ts.map +1 -0
- package/dist/src/server/index.js +5 -0
- package/dist/src/server/index.js.map +1 -0
- package/dist/src/server/mcp-server.d.ts +80 -0
- package/dist/src/server/mcp-server.d.ts.map +1 -0
- package/dist/src/server/mcp-server.js +263 -0
- package/dist/src/server/mcp-server.js.map +1 -0
- package/dist/src/services/index.d.ts +5 -0
- package/dist/src/services/index.d.ts.map +1 -0
- package/dist/src/services/index.js +5 -0
- package/dist/src/services/index.js.map +1 -0
- package/dist/src/services/memory-service.d.ts +105 -0
- package/dist/src/services/memory-service.d.ts.map +1 -0
- package/dist/src/services/memory-service.js +447 -0
- package/dist/src/services/memory-service.js.map +1 -0
- package/dist/src/storage/frontmatter-parser.d.ts +69 -0
- package/dist/src/storage/frontmatter-parser.d.ts.map +1 -0
- package/dist/src/storage/frontmatter-parser.js +207 -0
- package/dist/src/storage/frontmatter-parser.js.map +1 -0
- package/dist/src/storage/index.d.ts +6 -0
- package/dist/src/storage/index.d.ts.map +1 -0
- package/dist/src/storage/index.js +6 -0
- package/dist/src/storage/index.js.map +1 -0
- package/dist/src/storage/markdown-storage.d.ts +76 -0
- package/dist/src/storage/markdown-storage.d.ts.map +1 -0
- package/dist/src/storage/markdown-storage.js +193 -0
- package/dist/src/storage/markdown-storage.js.map +1 -0
- package/dist/src/utils/index.d.ts +5 -0
- package/dist/src/utils/index.d.ts.map +1 -0
- package/dist/src/utils/index.js +5 -0
- package/dist/src/utils/index.js.map +1 -0
- package/dist/src/utils/slugify.d.ts +24 -0
- package/dist/src/utils/slugify.d.ts.map +1 -0
- package/dist/src/utils/slugify.js +56 -0
- package/dist/src/utils/slugify.js.map +1 -0
- package/docs/architecture.md +349 -0
- package/docs/contracts.md +119 -0
- package/docs/prompt-template.md +79 -0
- package/docs/proposal-close-gates.md +58 -0
- package/docs/tool-calling-policy.md +107 -0
- package/package.json +53 -0
- package/src/contracts/index.ts +12 -0
- package/src/contracts/mcp.ts +303 -0
- package/src/contracts/schemas.ts +311 -0
- package/src/contracts/types.ts +414 -0
- package/src/index.ts +8 -0
- package/src/server/index.ts +5 -0
- package/src/server/mcp-server.ts +352 -0
- package/src/services/index.ts +5 -0
- package/src/services/memory-service.ts +548 -0
- package/src/storage/frontmatter-parser.ts +243 -0
- package/src/storage/index.ts +6 -0
- package/src/storage/markdown-storage.ts +236 -0
- package/src/utils/index.ts +5 -0
- package/src/utils/slugify.ts +63 -0
- package/test/contracts/schemas.test.ts +313 -0
- package/test/contracts/types.test.ts +21 -0
- package/test/frontmatter-parser-more.test.ts +94 -0
- package/test/server/mcp-server-internals.test.ts +257 -0
- package/test/server/mcp-server.test.ts +97 -0
- package/test/services/memory-service-edge.test.ts +248 -0
- package/test/services/memory-service.test.ts +279 -0
- package/test/storage/frontmatter-parser.test.ts +223 -0
- package/test/storage/markdown-storage.test.ts +217 -0
- package/test/storage/storage-edge.test.ts +238 -0
- package/test/utils/slugify-edge.test.ts +94 -0
- package/test/utils/slugify.test.ts +68 -0
- package/tsconfig.json +26 -0
- package/tsconfig.test.json +8 -0
- package/vitest.config.ts +27 -0
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: openspec-propose
|
|
3
|
+
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
|
|
4
|
+
license: MIT
|
|
5
|
+
compatibility: Requires openspec CLI.
|
|
6
|
+
metadata:
|
|
7
|
+
author: openspec
|
|
8
|
+
version: "1.0"
|
|
9
|
+
generatedBy: "1.2.0"
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
Propose a new change - create the change and generate all artifacts in one step.
|
|
13
|
+
|
|
14
|
+
I'll create a change with artifacts:
|
|
15
|
+
- proposal.md (what & why)
|
|
16
|
+
- design.md (how)
|
|
17
|
+
- tasks.md (implementation steps)
|
|
18
|
+
|
|
19
|
+
When ready to implement, run /opsx:apply
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
|
|
24
|
+
|
|
25
|
+
**Steps**
|
|
26
|
+
|
|
27
|
+
1. **If no clear input provided, ask what they want to build**
|
|
28
|
+
|
|
29
|
+
Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
|
|
30
|
+
> "What change do you want to work on? Describe what you want to build or fix."
|
|
31
|
+
|
|
32
|
+
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
|
|
33
|
+
|
|
34
|
+
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
|
|
35
|
+
|
|
36
|
+
2. **Create the change directory**
|
|
37
|
+
```bash
|
|
38
|
+
openspec new change "<name>"
|
|
39
|
+
```
|
|
40
|
+
This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
|
|
41
|
+
|
|
42
|
+
3. **Get the artifact build order**
|
|
43
|
+
```bash
|
|
44
|
+
openspec status --change "<name>" --json
|
|
45
|
+
```
|
|
46
|
+
Parse the JSON to get:
|
|
47
|
+
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
|
|
48
|
+
- `artifacts`: list of all artifacts with their status and dependencies
|
|
49
|
+
|
|
50
|
+
4. **Create artifacts in sequence until apply-ready**
|
|
51
|
+
|
|
52
|
+
Use the **TodoWrite tool** to track progress through the artifacts.
|
|
53
|
+
|
|
54
|
+
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
|
|
55
|
+
|
|
56
|
+
a. **For each artifact that is `ready` (dependencies satisfied)**:
|
|
57
|
+
- Get instructions:
|
|
58
|
+
```bash
|
|
59
|
+
openspec instructions <artifact-id> --change "<name>" --json
|
|
60
|
+
```
|
|
61
|
+
- The instructions JSON includes:
|
|
62
|
+
- `context`: Project background (constraints for you - do NOT include in output)
|
|
63
|
+
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
|
|
64
|
+
- `template`: The structure to use for your output file
|
|
65
|
+
- `instruction`: Schema-specific guidance for this artifact type
|
|
66
|
+
- `outputPath`: Where to write the artifact
|
|
67
|
+
- `dependencies`: Completed artifacts to read for context
|
|
68
|
+
- Read any completed dependency files for context
|
|
69
|
+
- Create the artifact file using `template` as the structure
|
|
70
|
+
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
|
|
71
|
+
- Show brief progress: "Created <artifact-id>"
|
|
72
|
+
|
|
73
|
+
b. **Continue until all `applyRequires` artifacts are complete**
|
|
74
|
+
- After creating each artifact, re-run `openspec status --change "<name>" --json`
|
|
75
|
+
- Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
|
|
76
|
+
- Stop when all `applyRequires` artifacts are done
|
|
77
|
+
|
|
78
|
+
c. **If an artifact requires user input** (unclear context):
|
|
79
|
+
- Use **AskUserQuestion tool** to clarify
|
|
80
|
+
- Then continue with creation
|
|
81
|
+
|
|
82
|
+
5. **Show final status**
|
|
83
|
+
```bash
|
|
84
|
+
openspec status --change "<name>"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Output**
|
|
88
|
+
|
|
89
|
+
After completing all artifacts, summarize:
|
|
90
|
+
- Change name and location
|
|
91
|
+
- List of artifacts created with brief descriptions
|
|
92
|
+
- What's ready: "All artifacts created! Ready for implementation."
|
|
93
|
+
- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
|
|
94
|
+
|
|
95
|
+
**Artifact Creation Guidelines**
|
|
96
|
+
|
|
97
|
+
- Follow the `instruction` field from `openspec instructions` for each artifact type
|
|
98
|
+
- The schema defines what each artifact should contain - follow it
|
|
99
|
+
- Read dependency artifacts for context before creating new ones
|
|
100
|
+
- Use `template` as the structure for your output file - fill in its sections
|
|
101
|
+
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
|
102
|
+
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
|
103
|
+
- These guide what you write, but should never appear in the output
|
|
104
|
+
|
|
105
|
+
**Guardrails**
|
|
106
|
+
- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
|
|
107
|
+
- Always read dependency artifacts before creating a new one
|
|
108
|
+
- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
|
|
109
|
+
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
|
110
|
+
- Verify each artifact file exists after writing before proceeding to next
|
package/.prettierrc
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# MemHub
|
|
2
|
+
|
|
3
|
+
Git-friendly memory MCP server for coding agents.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Why MemHub
|
|
10
|
+
|
|
11
|
+
- **Git-native**: all memory is plain text files
|
|
12
|
+
- **Agent-friendly**: exposed as MCP tools over stdio
|
|
13
|
+
- **Human-readable**: YAML metadata + Markdown body
|
|
14
|
+
- **Quality-gated**: lint + typecheck + tests + coverage gate
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
- Markdown-based memory storage (`.md`)
|
|
21
|
+
- YAML Front Matter metadata (`id`, `tags`, `category`, `importance`, timestamps)
|
|
22
|
+
- CRUD operations for memory entries
|
|
23
|
+
- Filtering, pagination, and full-text search
|
|
24
|
+
- Category/tag aggregation
|
|
25
|
+
- MCP stdio server compatible with MCP clients
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
30
|
+
|
|
31
|
+
### 1) Install dependencies
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### 2) Build
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm run build
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### 3) Run quality gate
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm run quality
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Use as MCP Server (stdio)
|
|
52
|
+
|
|
53
|
+
Example MCP client config:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"memhub": {
|
|
59
|
+
"command": "node",
|
|
60
|
+
"args": ["dist/server/mcp-server.js"],
|
|
61
|
+
"env": {
|
|
62
|
+
"MEMHUB_STORAGE_PATH": "/absolute/path/to/memories",
|
|
63
|
+
"MEMHUB_LOG_LEVEL": "info"
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
> If you publish to npm and install globally, you can also run through your package bin entry.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## Environment Variables
|
|
75
|
+
|
|
76
|
+
- `MEMHUB_STORAGE_PATH` (default: `./memories`)
|
|
77
|
+
- `MEMHUB_LOG_LEVEL` (default: `info`, options: `debug|info|warn|error`)
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Memory File Format
|
|
82
|
+
|
|
83
|
+
```markdown
|
|
84
|
+
---
|
|
85
|
+
id: "550e8400-e29b-41d4-a716-446655440000"
|
|
86
|
+
created_at: "2026-03-03T08:00:00.000Z"
|
|
87
|
+
updated_at: "2026-03-03T08:00:00.000Z"
|
|
88
|
+
tags:
|
|
89
|
+
- architecture
|
|
90
|
+
- tdd
|
|
91
|
+
category: "engineering"
|
|
92
|
+
importance: 4
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
# Contract-first MCP design
|
|
96
|
+
|
|
97
|
+
Define tool contracts and schemas before implementation.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Filename format:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
YYYY-MM-DD-title-slug.md
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## MCP Tools
|
|
109
|
+
|
|
110
|
+
- `memory_load`
|
|
111
|
+
First-turn tool. Load STM context for the current task/session.
|
|
112
|
+
- `memory_update`
|
|
113
|
+
Final-turn tool. Write back decisions, preferences, knowledge, and task-state updates.
|
|
114
|
+
|
|
115
|
+
Calling policy: see `docs/tool-calling-policy.md`.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Development
|
|
120
|
+
|
|
121
|
+
### Scripts
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
npm run build
|
|
125
|
+
npm run lint
|
|
126
|
+
npm run typecheck
|
|
127
|
+
npm run test
|
|
128
|
+
npm run test:coverage
|
|
129
|
+
npm run quality
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Engineering Workflow
|
|
133
|
+
|
|
134
|
+
- Contract-first (types + schema first)
|
|
135
|
+
- TDD (`red -> green -> refactor`)
|
|
136
|
+
- Quality gate enforced before merge
|
|
137
|
+
- Coverage threshold: **>= 80%**
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Project Structure
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
memhub/
|
|
145
|
+
├── docs/
|
|
146
|
+
├── src/
|
|
147
|
+
│ ├── contracts/
|
|
148
|
+
│ ├── server/
|
|
149
|
+
│ ├── services/
|
|
150
|
+
│ ├── storage/
|
|
151
|
+
│ └── utils/
|
|
152
|
+
├── test/
|
|
153
|
+
└── .github/workflows/
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Roadmap
|
|
159
|
+
|
|
160
|
+
- [x] Architecture and contracts
|
|
161
|
+
- [x] Core storage/service/server implementation
|
|
162
|
+
- [x] Quality gate (lint/typecheck/test/coverage)
|
|
163
|
+
- [ ] Integration tests
|
|
164
|
+
- [ ] Performance improvements
|
|
165
|
+
- [ ] npm release
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
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
|
+
- **Git 原生**:所有记忆都是纯文本文件,天然可 diff / 可回滚
|
|
12
|
+
- **面向 Agent**:通过 MCP(stdio)暴露工具,便于模型调用
|
|
13
|
+
- **人类可读**:元数据在 YAML,正文在 Markdown
|
|
14
|
+
- **质量可控**:内置 lint / typecheck / test / coverage 门禁
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 核心特性
|
|
19
|
+
|
|
20
|
+
- Markdown 持久化(`.md`)
|
|
21
|
+
- YAML Front Matter 元数据(`id / tags / category / importance / 时间戳`)
|
|
22
|
+
- 记忆条目的增删改查(CRUD)
|
|
23
|
+
- 支持过滤、分页、全文检索
|
|
24
|
+
- 分类/标签聚合能力
|
|
25
|
+
- MCP stdio server,可接入主流 MCP 客户端
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 快速开始
|
|
30
|
+
|
|
31
|
+
### 1)安装依赖
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### 2)构建
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm run build
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### 3)执行质量门禁
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm run quality
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 作为 MCP Server 使用(stdio)
|
|
52
|
+
|
|
53
|
+
在你的 MCP 客户端配置中添加:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"memhub": {
|
|
59
|
+
"command": "node",
|
|
60
|
+
"args": ["dist/server/mcp-server.js"],
|
|
61
|
+
"env": {
|
|
62
|
+
"MEMHUB_STORAGE_PATH": "/绝对路径/你的记忆目录",
|
|
63
|
+
"MEMHUB_LOG_LEVEL": "info"
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
> 若后续发布到 npm 并全局安装,也可以改为通过包的 bin 入口启动。
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 环境变量
|
|
75
|
+
|
|
76
|
+
- `MEMHUB_STORAGE_PATH`:记忆存储目录(默认:`./memories`)
|
|
77
|
+
- `MEMHUB_LOG_LEVEL`:日志级别(默认:`info`,可选:`debug|info|warn|error`)
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 记忆文件格式
|
|
82
|
+
|
|
83
|
+
```markdown
|
|
84
|
+
---
|
|
85
|
+
id: "550e8400-e29b-41d4-a716-446655440000"
|
|
86
|
+
created_at: "2026-03-03T08:00:00.000Z"
|
|
87
|
+
updated_at: "2026-03-03T08:00:00.000Z"
|
|
88
|
+
tags:
|
|
89
|
+
- architecture
|
|
90
|
+
- tdd
|
|
91
|
+
category: "engineering"
|
|
92
|
+
importance: 4
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
# Contract-first MCP 设计
|
|
96
|
+
|
|
97
|
+
先定义工具契约与 schema,再进入实现。
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
文件名格式:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
YYYY-MM-DD-title-slug.md
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## MCP 工具列表
|
|
109
|
+
|
|
110
|
+
> 调用策略建议见:`docs/tool-calling-policy.md`(首轮 `memory_load`,末轮 `memory_update`)。
|
|
111
|
+
|
|
112
|
+
- `memory_load`:首轮加载短期记忆(STM)上下文
|
|
113
|
+
- `memory_update`:末轮回写决策/偏好/知识/状态变化
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 开发说明
|
|
118
|
+
|
|
119
|
+
### 常用脚本
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm run build
|
|
123
|
+
npm run lint
|
|
124
|
+
npm run typecheck
|
|
125
|
+
npm run test
|
|
126
|
+
npm run test:coverage
|
|
127
|
+
npm run quality
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 工程流程(默认)
|
|
131
|
+
|
|
132
|
+
- 契约优先(先类型与 schema)
|
|
133
|
+
- 严格 TDD(`红 -> 绿 -> 重构`)
|
|
134
|
+
- 合并前必须通过质量门禁
|
|
135
|
+
- 覆盖率阈值:**>= 80%**
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 项目结构
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
memhub/
|
|
143
|
+
├── docs/
|
|
144
|
+
├── src/
|
|
145
|
+
│ ├── contracts/
|
|
146
|
+
│ ├── server/
|
|
147
|
+
│ ├── services/
|
|
148
|
+
│ ├── storage/
|
|
149
|
+
│ └── utils/
|
|
150
|
+
├── test/
|
|
151
|
+
└── .github/workflows/
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 路线图
|
|
157
|
+
|
|
158
|
+
- [x] 架构与契约设计
|
|
159
|
+
- [x] 核心实现(storage/service/server)
|
|
160
|
+
- [x] 质量门禁(lint/typecheck/test/coverage)
|
|
161
|
+
- [ ] 集成测试
|
|
162
|
+
- [ ] 性能优化
|
|
163
|
+
- [ ] npm 发布
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## License
|
|
168
|
+
|
|
169
|
+
MIT
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,cAAc,CAAC;AAG7B,cAAc,UAAU,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,UAAU;AACV,cAAc,cAAc,CAAC;AAE7B,qBAAqB;AACrB,cAAc,UAAU,CAAC"}
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP (Model Context Protocol) specific types and constants
|
|
3
|
+
* Defines the protocol structures for stdio-based communication
|
|
4
|
+
*/
|
|
5
|
+
import type { Memory } from './types.js';
|
|
6
|
+
/** Current MCP protocol version */
|
|
7
|
+
export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
|
|
8
|
+
/** Server information */
|
|
9
|
+
export declare const SERVER_INFO: {
|
|
10
|
+
readonly name: "memhub";
|
|
11
|
+
readonly version: "0.1.0";
|
|
12
|
+
};
|
|
13
|
+
/** JSON-RPC request ID */
|
|
14
|
+
export type RequestId = string | number;
|
|
15
|
+
/** Base JSON-RPC request structure */
|
|
16
|
+
export interface JsonRpcRequest<T = unknown> {
|
|
17
|
+
jsonrpc: '2.0';
|
|
18
|
+
id?: RequestId;
|
|
19
|
+
method: string;
|
|
20
|
+
params?: T;
|
|
21
|
+
}
|
|
22
|
+
/** Base JSON-RPC response structure */
|
|
23
|
+
export interface JsonRpcResponse<T = unknown> {
|
|
24
|
+
jsonrpc: '2.0';
|
|
25
|
+
id: RequestId | null;
|
|
26
|
+
result?: T;
|
|
27
|
+
error?: JsonRpcError;
|
|
28
|
+
}
|
|
29
|
+
/** JSON-RPC error structure */
|
|
30
|
+
export interface JsonRpcError {
|
|
31
|
+
code: number;
|
|
32
|
+
message: string;
|
|
33
|
+
data?: unknown;
|
|
34
|
+
}
|
|
35
|
+
/** JSON-RPC notification (no response expected) */
|
|
36
|
+
export interface JsonRpcNotification<T = unknown> {
|
|
37
|
+
jsonrpc: '2.0';
|
|
38
|
+
method: string;
|
|
39
|
+
params?: T;
|
|
40
|
+
}
|
|
41
|
+
/** Initialize request parameters */
|
|
42
|
+
export interface InitializeParams {
|
|
43
|
+
protocolVersion: string;
|
|
44
|
+
capabilities: ClientCapabilities;
|
|
45
|
+
clientInfo: Implementation;
|
|
46
|
+
}
|
|
47
|
+
/** Initialize result */
|
|
48
|
+
export interface InitializeResult {
|
|
49
|
+
protocolVersion: string;
|
|
50
|
+
capabilities: ServerCapabilities;
|
|
51
|
+
serverInfo: Implementation;
|
|
52
|
+
}
|
|
53
|
+
/** Implementation information */
|
|
54
|
+
export interface Implementation {
|
|
55
|
+
name: string;
|
|
56
|
+
version: string;
|
|
57
|
+
}
|
|
58
|
+
/** Client capabilities */
|
|
59
|
+
export interface ClientCapabilities {
|
|
60
|
+
readonly experimental?: Record<string, unknown>;
|
|
61
|
+
readonly roots?: {
|
|
62
|
+
listChanged?: boolean;
|
|
63
|
+
};
|
|
64
|
+
readonly sampling?: Record<string, unknown>;
|
|
65
|
+
}
|
|
66
|
+
/** Server capabilities */
|
|
67
|
+
export interface ServerCapabilities {
|
|
68
|
+
readonly experimental?: Record<string, unknown>;
|
|
69
|
+
readonly logging?: Record<string, unknown>;
|
|
70
|
+
readonly prompts?: {
|
|
71
|
+
listChanged?: boolean;
|
|
72
|
+
};
|
|
73
|
+
readonly resources?: {
|
|
74
|
+
subscribe?: boolean;
|
|
75
|
+
listChanged?: boolean;
|
|
76
|
+
};
|
|
77
|
+
readonly tools?: {
|
|
78
|
+
listChanged?: boolean;
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
/** Tool definition for tool/list */
|
|
82
|
+
export interface Tool {
|
|
83
|
+
name: string;
|
|
84
|
+
description: string;
|
|
85
|
+
inputSchema: ToolInputSchema;
|
|
86
|
+
}
|
|
87
|
+
/** Tool input schema (JSON Schema) */
|
|
88
|
+
export interface ToolInputSchema {
|
|
89
|
+
type: 'object';
|
|
90
|
+
properties?: Record<string, unknown>;
|
|
91
|
+
required?: string[];
|
|
92
|
+
additionalProperties?: boolean;
|
|
93
|
+
}
|
|
94
|
+
/** Tool call request */
|
|
95
|
+
export interface ToolCallRequest {
|
|
96
|
+
name: string;
|
|
97
|
+
arguments?: Record<string, unknown>;
|
|
98
|
+
}
|
|
99
|
+
/** Tool call result */
|
|
100
|
+
export interface ToolCallResult {
|
|
101
|
+
content: ToolContent[];
|
|
102
|
+
isError?: boolean;
|
|
103
|
+
}
|
|
104
|
+
/** Tool content types */
|
|
105
|
+
export type ToolContent = TextContent | ImageContent;
|
|
106
|
+
/** Text content */
|
|
107
|
+
export interface TextContent {
|
|
108
|
+
type: 'text';
|
|
109
|
+
text: string;
|
|
110
|
+
}
|
|
111
|
+
/** Image content */
|
|
112
|
+
export interface ImageContent {
|
|
113
|
+
type: 'image';
|
|
114
|
+
data: string;
|
|
115
|
+
mimeType: string;
|
|
116
|
+
}
|
|
117
|
+
/** All available tool names */
|
|
118
|
+
export declare const TOOL_NAMES: readonly ["memory_load", "memory_update"];
|
|
119
|
+
/** Tool name type */
|
|
120
|
+
export type ToolName = (typeof TOOL_NAMES)[number];
|
|
121
|
+
/** Tool definitions for MCP server */
|
|
122
|
+
export declare const TOOL_DEFINITIONS: readonly Tool[];
|
|
123
|
+
/** All MCP method names */
|
|
124
|
+
export declare const MCP_METHODS: {
|
|
125
|
+
readonly INITIALIZE: "initialize";
|
|
126
|
+
readonly INITIALIZED: "notifications/initialized";
|
|
127
|
+
readonly SHUTDOWN: "shutdown";
|
|
128
|
+
readonly EXIT: "exit";
|
|
129
|
+
readonly TOOLS_LIST: "tools/list";
|
|
130
|
+
readonly TOOLS_CALL: "tools/call";
|
|
131
|
+
readonly LOGGING_MESSAGE: "notifications/message";
|
|
132
|
+
readonly PROGRESS: "notifications/progress";
|
|
133
|
+
};
|
|
134
|
+
/** Standard JSON-RPC error codes */
|
|
135
|
+
export declare const JSONRPC_ERROR_CODES: {
|
|
136
|
+
readonly PARSE_ERROR: -32700;
|
|
137
|
+
readonly INVALID_REQUEST: -32600;
|
|
138
|
+
readonly METHOD_NOT_FOUND: -32601;
|
|
139
|
+
readonly INVALID_PARAMS: -32602;
|
|
140
|
+
readonly INTERNAL_ERROR: -32603;
|
|
141
|
+
};
|
|
142
|
+
/** MemHub custom error codes */
|
|
143
|
+
export declare const MEMHUB_ERROR_CODES: {
|
|
144
|
+
readonly NOT_FOUND: -32001;
|
|
145
|
+
readonly STORAGE_ERROR: -32002;
|
|
146
|
+
readonly VALIDATION_ERROR: -32003;
|
|
147
|
+
readonly DUPLICATE_ERROR: -32004;
|
|
148
|
+
};
|
|
149
|
+
/** Combined error codes */
|
|
150
|
+
export declare const ERROR_CODES: {
|
|
151
|
+
readonly NOT_FOUND: -32001;
|
|
152
|
+
readonly STORAGE_ERROR: -32002;
|
|
153
|
+
readonly VALIDATION_ERROR: -32003;
|
|
154
|
+
readonly DUPLICATE_ERROR: -32004;
|
|
155
|
+
readonly PARSE_ERROR: -32700;
|
|
156
|
+
readonly INVALID_REQUEST: -32600;
|
|
157
|
+
readonly METHOD_NOT_FOUND: -32601;
|
|
158
|
+
readonly INVALID_PARAMS: -32602;
|
|
159
|
+
readonly INTERNAL_ERROR: -32603;
|
|
160
|
+
};
|
|
161
|
+
/** Helper type to extract result type from a tool name */
|
|
162
|
+
export type ToolResult<T extends ToolName> = T extends 'memory_load' ? {
|
|
163
|
+
items: Memory[];
|
|
164
|
+
total: number;
|
|
165
|
+
} : T extends 'memory_update' ? {
|
|
166
|
+
id: string;
|
|
167
|
+
sessionId: string;
|
|
168
|
+
filePath: string;
|
|
169
|
+
created: boolean;
|
|
170
|
+
updated: boolean;
|
|
171
|
+
memory: Memory;
|
|
172
|
+
} : never;
|
|
173
|
+
/** Helper type to extract input type from a tool name */
|
|
174
|
+
export type ToolInput<T extends ToolName> = T extends 'memory_load' ? {
|
|
175
|
+
id?: string;
|
|
176
|
+
sessionId?: string;
|
|
177
|
+
date?: string;
|
|
178
|
+
query?: string;
|
|
179
|
+
category?: string;
|
|
180
|
+
tags?: string[];
|
|
181
|
+
limit?: number;
|
|
182
|
+
scope?: 'stm' | 'all';
|
|
183
|
+
} : T extends 'memory_update' ? {
|
|
184
|
+
id?: string;
|
|
185
|
+
sessionId?: string;
|
|
186
|
+
mode?: 'append' | 'upsert';
|
|
187
|
+
entryType?: 'decision' | 'preference' | 'knowledge' | 'todo' | 'state_change';
|
|
188
|
+
title?: string;
|
|
189
|
+
content: string;
|
|
190
|
+
tags?: string[];
|
|
191
|
+
category?: string;
|
|
192
|
+
importance?: number;
|
|
193
|
+
} : never;
|
|
194
|
+
//# sourceMappingURL=mcp.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../../src/contracts/mcp.ts"],"names":[],"mappings":"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"}
|