@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.
Files changed (104) hide show
  1. package/.eslintrc.cjs +46 -0
  2. package/.github/workflows/ci.yml +74 -0
  3. package/.iflow/commands/opsx-apply.md +152 -0
  4. package/.iflow/commands/opsx-archive.md +157 -0
  5. package/.iflow/commands/opsx-explore.md +173 -0
  6. package/.iflow/commands/opsx-propose.md +106 -0
  7. package/.iflow/skills/openspec-apply-change/SKILL.md +156 -0
  8. package/.iflow/skills/openspec-archive-change/SKILL.md +114 -0
  9. package/.iflow/skills/openspec-explore/SKILL.md +288 -0
  10. package/.iflow/skills/openspec-propose/SKILL.md +110 -0
  11. package/.prettierrc +11 -0
  12. package/README.md +171 -0
  13. package/README.zh-CN.md +169 -0
  14. package/dist/src/contracts/index.d.ts +7 -0
  15. package/dist/src/contracts/index.d.ts.map +1 -0
  16. package/dist/src/contracts/index.js +10 -0
  17. package/dist/src/contracts/index.js.map +1 -0
  18. package/dist/src/contracts/mcp.d.ts +194 -0
  19. package/dist/src/contracts/mcp.d.ts.map +1 -0
  20. package/dist/src/contracts/mcp.js +112 -0
  21. package/dist/src/contracts/mcp.js.map +1 -0
  22. package/dist/src/contracts/schemas.d.ts +1153 -0
  23. package/dist/src/contracts/schemas.d.ts.map +1 -0
  24. package/dist/src/contracts/schemas.js +246 -0
  25. package/dist/src/contracts/schemas.js.map +1 -0
  26. package/dist/src/contracts/types.d.ts +328 -0
  27. package/dist/src/contracts/types.d.ts.map +1 -0
  28. package/dist/src/contracts/types.js +30 -0
  29. package/dist/src/contracts/types.js.map +1 -0
  30. package/dist/src/index.d.ts +8 -0
  31. package/dist/src/index.d.ts.map +1 -0
  32. package/dist/src/index.js +8 -0
  33. package/dist/src/index.js.map +1 -0
  34. package/dist/src/server/index.d.ts +5 -0
  35. package/dist/src/server/index.d.ts.map +1 -0
  36. package/dist/src/server/index.js +5 -0
  37. package/dist/src/server/index.js.map +1 -0
  38. package/dist/src/server/mcp-server.d.ts +80 -0
  39. package/dist/src/server/mcp-server.d.ts.map +1 -0
  40. package/dist/src/server/mcp-server.js +263 -0
  41. package/dist/src/server/mcp-server.js.map +1 -0
  42. package/dist/src/services/index.d.ts +5 -0
  43. package/dist/src/services/index.d.ts.map +1 -0
  44. package/dist/src/services/index.js +5 -0
  45. package/dist/src/services/index.js.map +1 -0
  46. package/dist/src/services/memory-service.d.ts +105 -0
  47. package/dist/src/services/memory-service.d.ts.map +1 -0
  48. package/dist/src/services/memory-service.js +447 -0
  49. package/dist/src/services/memory-service.js.map +1 -0
  50. package/dist/src/storage/frontmatter-parser.d.ts +69 -0
  51. package/dist/src/storage/frontmatter-parser.d.ts.map +1 -0
  52. package/dist/src/storage/frontmatter-parser.js +207 -0
  53. package/dist/src/storage/frontmatter-parser.js.map +1 -0
  54. package/dist/src/storage/index.d.ts +6 -0
  55. package/dist/src/storage/index.d.ts.map +1 -0
  56. package/dist/src/storage/index.js +6 -0
  57. package/dist/src/storage/index.js.map +1 -0
  58. package/dist/src/storage/markdown-storage.d.ts +76 -0
  59. package/dist/src/storage/markdown-storage.d.ts.map +1 -0
  60. package/dist/src/storage/markdown-storage.js +193 -0
  61. package/dist/src/storage/markdown-storage.js.map +1 -0
  62. package/dist/src/utils/index.d.ts +5 -0
  63. package/dist/src/utils/index.d.ts.map +1 -0
  64. package/dist/src/utils/index.js +5 -0
  65. package/dist/src/utils/index.js.map +1 -0
  66. package/dist/src/utils/slugify.d.ts +24 -0
  67. package/dist/src/utils/slugify.d.ts.map +1 -0
  68. package/dist/src/utils/slugify.js +56 -0
  69. package/dist/src/utils/slugify.js.map +1 -0
  70. package/docs/architecture.md +349 -0
  71. package/docs/contracts.md +119 -0
  72. package/docs/prompt-template.md +79 -0
  73. package/docs/proposal-close-gates.md +58 -0
  74. package/docs/tool-calling-policy.md +107 -0
  75. package/package.json +53 -0
  76. package/src/contracts/index.ts +12 -0
  77. package/src/contracts/mcp.ts +303 -0
  78. package/src/contracts/schemas.ts +311 -0
  79. package/src/contracts/types.ts +414 -0
  80. package/src/index.ts +8 -0
  81. package/src/server/index.ts +5 -0
  82. package/src/server/mcp-server.ts +352 -0
  83. package/src/services/index.ts +5 -0
  84. package/src/services/memory-service.ts +548 -0
  85. package/src/storage/frontmatter-parser.ts +243 -0
  86. package/src/storage/index.ts +6 -0
  87. package/src/storage/markdown-storage.ts +236 -0
  88. package/src/utils/index.ts +5 -0
  89. package/src/utils/slugify.ts +63 -0
  90. package/test/contracts/schemas.test.ts +313 -0
  91. package/test/contracts/types.test.ts +21 -0
  92. package/test/frontmatter-parser-more.test.ts +94 -0
  93. package/test/server/mcp-server-internals.test.ts +257 -0
  94. package/test/server/mcp-server.test.ts +97 -0
  95. package/test/services/memory-service-edge.test.ts +248 -0
  96. package/test/services/memory-service.test.ts +279 -0
  97. package/test/storage/frontmatter-parser.test.ts +223 -0
  98. package/test/storage/markdown-storage.test.ts +217 -0
  99. package/test/storage/storage-edge.test.ts +238 -0
  100. package/test/utils/slugify-edge.test.ts +94 -0
  101. package/test/utils/slugify.test.ts +68 -0
  102. package/tsconfig.json +26 -0
  103. package/tsconfig.test.json +8 -0
  104. 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
@@ -0,0 +1,11 @@
1
+ {
2
+ "semi": true,
3
+ "trailingComma": "es5",
4
+ "singleQuote": true,
5
+ "printWidth": 100,
6
+ "tabWidth": 2,
7
+ "useTabs": false,
8
+ "bracketSpacing": true,
9
+ "arrowParens": "avoid",
10
+ "endOfLine": "lf"
11
+ }
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
@@ -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,7 @@
1
+ /**
2
+ * Contract exports - Central export point for all types and schemas
3
+ */
4
+ export * from './types.js';
5
+ export * from './schemas.js';
6
+ export * from './mcp.js';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -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,10 @@
1
+ /**
2
+ * Contract exports - Central export point for all types and schemas
3
+ */
4
+ // Types
5
+ export * from './types.js';
6
+ // Schemas
7
+ export * from './schemas.js';
8
+ // MCP protocol types
9
+ export * from './mcp.js';
10
+ //# sourceMappingURL=index.js.map
@@ -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":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,yBAAyB;AACzB,eAAO,MAAM,WAAW;;;CAGd,CAAC;AAMX,0BAA0B;AAC1B,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,sCAAsC;AACtC,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ;AAED,uCAAuC;AACvC,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ;AAMD,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,wBAAwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,iCAAiC;AACjC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0BAA0B;AAC1B,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,0BAA0B;AAC1B,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC5C;AAMD,oCAAoC;AACpC,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,eAAe,CAAC;CAC9B;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,uBAAuB;AACvB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,YAAY,CAAC;AAErD,mBAAmB;AACnB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oBAAoB;AACpB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD,+BAA+B;AAC/B,eAAO,MAAM,UAAU,2CAA4C,CAAC;AAEpE,qBAAqB;AACrB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,SAAS,IAAI,EAmDlC,CAAC;AAMX,2BAA2B;AAC3B,eAAO,MAAM,WAAW;;;;;;;;;CAgBd,CAAC;AAMX,oCAAoC;AACpC,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX,gCAAgC;AAChC,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,2BAA2B;AAC3B,eAAO,MAAM,WAAW;;;;;;;;;;CAGd,CAAC;AAMX,0DAA0D;AAC1D,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GAChE;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC,CAAC,SAAS,eAAe,GACvB;IACE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD,KAAK,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GAC/D;IACE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CACvB,GACD,CAAC,SAAS,eAAe,GACvB;IACE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,SAAS,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,MAAM,GAAG,cAAc,CAAC;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD,KAAK,CAAC"}