@synth-coder/memhub 0.1.0

package/docs/architecture.md

@@ -0,0 +1,349 @@
+# MemHub 架构设计文档
+
+## 概述
+
+MemHub 是一个基于 Git 友好的记忆存储系统，使用 Markdown 格式存储记忆条目，通过 YAML Front Matter 存储元数据。它实现了 MCP (Model Context Protocol) Server，通过 stdio 进行通信。
+
+## 设计原则
+
+1. **Git 友好**: 所有数据以纯文本 Markdown 文件存储，天然支持版本控制
+2. **人类可读**: 记忆条目可以直接用文本编辑器打开阅读
+3. **简单优先**: 不使用数据库，避免复杂的迁移和锁定问题
+4. **契约先行**: 接口和类型定义先于实现
+5. **测试驱动**: 严格遵循 TDD (红-绿-重构)
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MCP Client                             │
+│                   (Claude Desktop, etc.)                    │
+└──────────────────────┬──────────────────────────────────────┘
+                       │ stdio
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    MemHub MCP Server                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  MCP Router  │  │   Services   │  │   Storage Layer  │  │
+│  │              │  │              │  │                  │  │
+│  │ - list_tools │  │ - create     │  │ - read memory    │  │
+│  │ - call_tool  │  │ - read       │  │ - write memory   │  │
+│  │              │  │ - update     │  │ - search index   │  │
+│  │              │  │ - delete     │  │ - list memories  │  │
+│  │              │  │ - search     │  │                  │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+                       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Markdown Storage                         │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  YYYY-MM-DD-title-slug.md                           │   │
+│  │  ─────────────────────────                          │   │
+│  │  ---                                                │   │
+│  │  id: uuid-v4                                        │   │
+│  │  created_at: ISO8601                                │   │
+│  │  updated_at: ISO8601                                │   │
+│  │  tags: [tag1, tag2]                                 │   │
+│  │  category: string                                   │   │
+│  │  importance: 1-5                                    │   │
+│  │  ---                                                │   │
+│  │                                                     │   │
+│  │  # Title                                            │   │
+│  │                                                     │   │
+│  │  Markdown content body...                           │   │
+│  │                                                     │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 核心组件
+
+### 1. MCP Server (src/server/mcp-server.ts)
+
+- 入口点，处理 stdio 通信
+- 实现 MCP 协议的生命周期管理
+- 路由工具调用到对应的服务
+
+### 2. Services (src/services/)
+
+业务逻辑层，包含：
+
+- **MemoryService**: 记忆 CRUD 操作
+- **SearchService**: 搜索和过滤
+- **IndexService**: 索引管理（可选，用于性能）
+
+### 3. Storage Layer (src/storage/)
+
+数据持久化层：
+
+- **MarkdownStorage**: Markdown 文件读写
+- **FrontMatterParser**: YAML Front Matter 解析
+- **FileSystem**: 文件系统抽象（便于测试）
+
+### 4. Contracts (src/contracts/)
+
+类型定义和 Zod 契约：
+
+- **types.ts**: TypeScript 类型
+- **schemas.ts**: Zod 验证模式
+- **mcp.ts**: MCP 协议相关类型
+
+## 数据模型
+
+### Memory Entry (记忆条目)
+
+```typescript
+interface Memory {
+  // Identity
+  id: string; // UUID v4
+
+  // Metadata (YAML Front Matter)
+  createdAt: string; // ISO 8601
+  updatedAt: string; // ISO 8601
+  tags: string[]; // 标签数组
+  category: string; // 分类
+  importance: number; // 1-5 重要性等级
+
+  // Content (Markdown Body)
+  title: string; // Markdown H1 标题
+  content: string; // Markdown 正文
+}
+```
+
+### File Naming Convention
+
+```
+{YYYY-MM-DD}-{title-slug}.md
+
+Examples:
+- 2024-03-15-project-kickoff.md
+- 2024-03-20-meeting-notes.md
+```
+
+### Markdown Format
+
+```markdown
+---
+id: '550e8400-e29b-41d4-a716-446655440000'
+created_at: '2024-03-15T10:30:00Z'
+updated_at: '2024-03-15T14:20:00Z'
+tags:
+  - project
+  - planning
+category: 'work'
+importance: 4
+---
+
+# Project Kickoff
+
+Today we started the new project...
+
+## Key Decisions
+
+- Decision 1
+- Decision 2
+```
+
+## MCP Tools
+
+### 1. `memory_create`
+
+创建新记忆条目。
+
+**Input:**
+
+- title: string (required)
+- content: string (required)
+- tags?: string[]
+- category?: string
+- importance?: number (1-5, default: 3)
+
+**Output:**
+
+- id: string
+- filePath: string
+
+### 2. `memory_read`
+
+读取记忆条目。
+
+**Input:**
+
+- id: string (required)
+
+**Output:**
+
+- Memory object
+
+### 3. `memory_update`
+
+更新记忆条目。
+
+**Input:**
+
+- id: string (required)
+- title?: string
+- content?: string
+- tags?: string[]
+- category?: string
+- importance?: number
+
+**Output:**
+
+- updated Memory object
+
+### 4. `memory_delete`
+
+删除记忆条目。
+
+**Input:**
+
+- id: string (required)
+
+**Output:**
+
+- success: boolean
+
+### 5. `memory_list`
+
+列出记忆条目（支持过滤和分页）。
+
+**Input:**
+
+- category?: string
+- tags?: string[]
+- fromDate?: string (ISO 8601)
+- toDate?: string (ISO 8601)
+- limit?: number (default: 20, max: 100)
+- offset?: number (default: 0)
+
+**Output:**
+
+- memories: Memory[]
+- total: number
+- hasMore: boolean
+
+### 6. `memory_search`
+
+全文搜索记忆。
+
+**Input:**
+
+- query: string (required)
+- limit?: number (default: 10)
+
+**Output:**
+
+- results: SearchResult[]
+  - memory: Memory
+  - score: number
+  - matches: string[]
+
+### 7. `memory_get_categories`
+
+获取所有分类。
+
+**Output:**
+
+- categories: string[]
+
+### 8. `memory_get_tags`
+
+获取所有标签。
+
+**Output:**
+
+- tags: string[]
+
+## 错误处理
+
+所有错误使用标准 MCP 错误格式：
+
+```typescript
+interface McpError {
+  code: number; // MCP error code
+  message: string; // Human readable message
+  data?: unknown; // Additional context
+}
+```
+
+错误码定义：
+
+- `INVALID_PARAMS`: 参数验证失败
+- `NOT_FOUND`: 记忆条目不存在
+- `STORAGE_ERROR`: 存储操作失败
+- `INTERNAL_ERROR`: 内部错误
+
+## 配置
+
+通过环境变量配置：
+
+```bash
+MEMHUB_STORAGE_PATH=/path/to/memories  # 存储目录，默认: ./memories
+MEMHUB_LOG_LEVEL=info                   # 日志级别: debug, info, warn, error
+```
+
+## 技术栈
+
+- **Runtime**: Node.js 18+
+- **Language**: TypeScript 5.3+
+- **Protocol**: MCP (Model Context Protocol)
+- **Transport**: stdio
+- **Validation**: Zod
+- **Testing**: Vitest (覆盖率 >= 80%)
+- **Linting**: ESLint + Prettier
+
+## 目录结构
+
+```
+memhub/
+├── docs/
+│   ├── architecture.md       # 本文档
+│   └── contracts.md          # 契约文档
+├── src/
+│   ├── contracts/            # 类型和契约
+│   │   ├── types.ts
+│   │   ├── schemas.ts
+│   │   └── mcp.ts
+│   ├── server/               # MCP Server
+│   │   └── mcp-server.ts
+│   ├── services/             # 业务逻辑
+│   │   ├── memory-service.ts
+│   │   └── search-service.ts
+│   ├── storage/              # 存储层
+│   │   ├── markdown-storage.ts
+│   │   └── frontmatter-parser.ts
+│   └── utils/                # 工具函数
+│       └── file-system.ts
+├── test/                     # 测试
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/
+├── .github/
+│   └── workflows/
+│       └── ci.yml            # CI 配置
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── .eslintrc.cjs
+├── .prettierrc
+└── README.md
+```
+
+## 开发流程
+
+1. **设计**: 先写架构文档和契约
+2. **契约**: 定义 TypeScript 类型和 Zod Schema
+3. **测试**: 编写红色测试（先失败）
+4. **实现**: 编写最小实现使测试通过（绿色）
+5. **重构**: 优化代码结构
+6. **重复**: 循环 3-5 步
+
+## 质量门禁
+
+- ✅ ESLint 无错误
+- ✅ Prettier 格式化检查通过
+- ✅ TypeScript 严格类型检查通过
+- ✅ 单元测试全部通过
+- ✅ 代码覆盖率 >= 80%

package/docs/contracts.md

@@ -0,0 +1,119 @@
+# MemHub 契约文档（vNext）
+
+当前对外 MCP 工具仅保留两项：
+
+1. `memory_load`（首轮）
+2. `memory_update`（末轮）
+
+目标是形成稳定闭环：**先读 STM，再回写 STM**。
+
+---
+
+## 1) memory_load
+
+用于用户输入后第一轮主动加载短期记忆。
+
+### 输入
+
+```ts
+interface MemoryLoadInput {
+  id?: string;                 // 指定单条记忆
+  sessionId?: string;          // 会话 UUID
+  date?: string;               // YYYY-MM-DD
+  query?: string;              // 文本检索
+  category?: string;
+  tags?: string[];
+  limit?: number;              // 默认 20
+  scope?: 'stm' | 'all';       // 默认 stm
+}
+```
+
+### 输出
+
+```ts
+interface MemoryLoadOutput {
+  items: Memory[];
+  total: number;
+}
+```
+
+---
+
+## 2) memory_update
+
+用于本轮结束前主动回写记忆。
+
+### 输入
+
+```ts
+type EntryType = 'decision' | 'preference' | 'knowledge' | 'todo' | 'state_change';
+
+interface MemoryUpdateInput {
+  id?: string;                 // 有 id 则更新；无 id 则追加
+  sessionId?: string;          // 无则服务端自动生成并返回
+  mode?: 'append' | 'upsert';  // 默认 append
+  entryType?: EntryType;
+  title?: string;
+  content: string;             // 必填
+  tags?: string[];
+  category?: string;
+  importance?: number;         // 1-5
+}
+```
+
+### 输出
+
+```ts
+interface MemoryUpdateOutput {
+  id: string;
+  sessionId: string;
+  filePath: string;
+  created: boolean;
+  updated: boolean;
+  memory: Memory;
+}
+```
+
+---
+
+## Memory 数据模型
+
+```ts
+interface Memory {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  sessionId?: string;
+  entryType?: EntryType;
+  tags: string[];
+  category: string;
+  importance: number;
+  title: string;
+  content: string;
+}
+```
+
+---
+
+## 存储路径契约（并发安全）
+
+为避免多个 CLI 同日写入冲突，采用分层目录：
+
+```text
+{storageRoot}/YYYY-MM-DD/{session_uuid}/{timestamp}-{slug}.md
+```
+
+例如：
+
+```text
+memories/2026-03-03/550e8400-e29b-41d4-a716-446655440111/2026-03-03T16-40-12-123Z-task-summary.md
+```
+
+---
+
+## 调用策略契约（强建议）
+
+- 用户输入后第一轮：调用 `memory_load`
+- 最终输出前最后一轮：调用 `memory_update`
+
+详细策略见：`docs/tool-calling-policy.md`

package/docs/prompt-template.md

@@ -0,0 +1,79 @@
+# Prompt Template for Coding Agents (MemHub STM Loop)
+
+Use this template in Codex / Claude Code / OpenCode system prompt or task preamble.
+
+---
+
+## System Rule: STM Closed Loop
+
+You are connected to MemHub MCP.
+
+### Mandatory tool-calling behavior
+
+1. **First round after receiving user prompt**: call `memory_load`.
+2. **Final round before sending final answer**: call `memory_update`.
+
+Do not skip these two calls unless tool is unavailable.
+
+---
+
+## Tool usage policy
+
+### On first round (`memory_load`)
+
+Call with the most specific context available:
+
+```json
+{
+  "sessionId": "<session-uuid-if-known>",
+  "scope": "stm",
+  "limit": 20
+}
+```
+
+If task is date-scoped, add `date: "YYYY-MM-DD"`.
+If task is keyword-driven, add `query`.
+
+### On final round (`memory_update`)
+
+Write only high-value context likely reused in next 3 turns:
+
+- decisions
+- preference changes
+- constraints
+- task state changes
+- reusable conclusions
+
+Example:
+
+```json
+{
+  "sessionId": "<session-uuid-if-known>",
+  "mode": "append",
+  "entryType": "decision",
+  "title": "Storage architecture decision",
+  "content": "Use date/session_uuid nested markdown storage to avoid multi-CLI collision.",
+  "tags": ["architecture", "storage", "stm"],
+  "category": "engineering",
+  "importance": 4
+}
+```
+
+---
+
+## Minimal execution checklist
+
+- [ ] First tool call is `memory_load`
+- [ ] Final tool call is `memory_update`
+- [ ] `memory_update` content is concise and reusable
+- [ ] No sensitive secrets in memory payload
+
+---
+
+## Failure fallback
+
+If tool call fails:
+
+1. continue task execution
+2. mention memory tool failure briefly in internal reasoning/logs
+3. still provide final user answer

package/docs/proposal-close-gates.md

@@ -0,0 +1,58 @@
+# Proposal: Close Remaining Quality Gates (Phase 2)
+
+## Context
+Current implementation already has broad functionality and passing test suites, but quality gates are still blocked by:
+
+1. ESLint configuration/type-aware parsing issues on test files
+2. TypeScript typecheck errors in server and storage/service imports
+3. Coverage gate failure on function coverage (<80%)
+4. Project path inconsistency (`workspace/workspace/memhub`)
+
+## Root Causes
+- ESLint `parserOptions.project` only pointed to `tsconfig.json`, while test files are not included there.
+- Some implementation details introduced strict-mode lint/type mismatches (`any` usage, fallthrough, readonly/no-unused issues).
+- Existing server tests focus on constants/contracts but not internal execution paths, leaving many functions uncovered.
+- Project was scaffolded under a nested directory.
+
+## Plan of Record
+
+### Step 1 — Fix static quality gates
+- Update ESLint type-aware project references to include test TS config.
+- Update `tsconfig.test.json` include set.
+- Fix strict lint/type issues in server/service/storage/utils modules.
+
+### Step 2 — Raise function coverage to >=80%
+- Add focused tests for MCP server runtime paths:
+  - JSON parsing failure path
+  - invalid request path
+  - method dispatch (`initialize`, `tools/list`, `tools/call`, unknown method)
+  - error handling (`ServiceError`, validation-like error, generic error)
+  - response/error serialization
+  - log filtering behavior
+- Preserve existing passing behavior and avoid over-mocking core service logic.
+
+### Step 3 — Validate full gate
+Run and require pass for:
+- `npm run lint`
+- `npm run typecheck`
+- `npm run test`
+- `npm run test:coverage` (global lines/functions/branches/statements >= 80)
+
+### Step 4 — Normalize repository location
+- Move project to `C:\Users\cloud_user\.openclaw\workspace\memhub` (if missing).
+- Verify scripts still run from new root.
+
+## Acceptance Criteria
+- No lint errors
+- No typecheck errors
+- All tests pass
+- Coverage thresholds all >= 80%
+- Repository available at normalized path
+
+## Risks and Mitigations
+- **Risk:** Private method tests become brittle.
+  - **Mitigation:** Test externally visible behavior and error contracts where possible; keep internals tests focused and minimal.
+- **Risk:** Path migration may break references.
+  - **Mitigation:** Move whole directory atomically and rerun full gate.
+- **Risk:** Coverage improvements skew test value.
+  - **Mitigation:** Prefer behavior-driven tests over shallow line-hitting.

package/docs/tool-calling-policy.md

@@ -0,0 +1,107 @@
+# Tool Calling Policy (STM-first)
+
+> 目标：让模型在每轮任务中稳定形成「先加载短期记忆，再产出，再回写记忆」的闭环。
+
+## 一、调用时序（强约束）
+
+1. **首轮调用 `memory_load`**（在响应用户前）
+   - 用于加载当前会话/任务相关短期记忆（STM）
+   - 若无命中，继续任务，不阻塞
+
+2. **末轮调用 `memory_update`**（在本轮输出结束前）
+   - 将本轮新增的关键上下文写回
+   - 重点写入：决策、约束变更、待办变化、关键结论
+
+---
+
+## 二、STM 判据（3 轮复用原则）
+
+若信息在未来 **3 轮** 内很可能被再次引用，则纳入 STM：
+
+- 当前任务目标/范围
+- 新确认的约束条件
+- 待办项与状态变化（pending / done）
+- 临时变量、参数、文件路径、报错栈
+- 用户明确修正/改口（需求切换）
+
+不满足则不强行写入，避免噪音。
+
+---
+
+## 三、建议工具定义（简化版）
+
+## `memory_load`
+**作用**：统一“看记忆”，用于当前轮开头加载上下文。
+
+**建议入参**：
+- `session_id`（可选，推荐）
+- `date`（可选，默认今天）
+- `limit`（可选，默认 20）
+- `tags`（可选）
+- `category`（可选）
+- `query`（可选）
+- `scope`（可选：`stm|all`，默认 `stm`）
+
+**建议返回**：
+- `items[]`（记忆条目）
+- `summary`（可选摘要）
+- `pending[]` / `done[]`（若可提取）
+
+---
+
+## `memory_update`
+**作用**：统一“写记忆”，用于当前轮末尾回写。
+
+**建议入参**：
+- `session_id`（可选；无则自动生成并返回）
+- `date`（可选，默认今天）
+- `mode`：`append|upsert`（默认 `append`）
+- `entry_type`：`decision|preference|knowledge|todo|state_change`
+- `title`
+- `content`
+- `tags[]`
+- `category`
+- `importance`（1-5）
+
+**建议返回**：
+- `id`
+- `session_id`
+- `file_path`
+- `created|updated`
+
+---
+
+## 四、并发与目录规范
+
+为支持多个 CLI 同时写入，建议目录如下：
+
+```text
+memories/
+  YYYY-MM-DD/
+    <session_uuid>/
+      2026-03-03T16-41-23.123Z-<slug>.md
+```
+
+说明：
+- 同一天按 `session_uuid` 分桶，避免并发冲突
+- 每条记录仍保留 YAML + Markdown 正文
+- `session_uuid` 可来自调用方；缺省由服务端生成
+
+---
+
+## 五、触发更新条件
+
+在以下事件发生时，优先触发 `memory_update`：
+
+- 用户显式改需求（如“换个方案”）
+- 任务状态切换（分析 → 实现 / 实现 → 验证）
+- 新信息与既有 STM 冲突
+- 本轮产出形成可复用结论
+
+---
+
+## 六、设计原则
+
+- **STM 保留细节，不做过度抽象**
+- **LTM 另层抽取，不与 STM 混存**
+- **先 load，后 update，形成闭环**