AI记忆存储服务

┌────────────────────┐   HTTP (JSON-RPC)   ┌───────────────┐
│  AI Agent (Claude) │ ◄─────────────────► │   MCP Server  │
└────────────────────┘    鉴权: Bearer      └───────┬───────┘
                                                    │
                          ┌──────────────┬──────────┴──────────┐
                          ▼              ▼                      ▼
                   ┌─────────────┐ ┌──────────┐        ┌────────────┐
                   │ grep/Scorer │ │ YAML 解析 │        │ Web Admin  │
                   └─────────────┘ └──────────┘        └────────────┘
                          │
                          ▼ (可选)
                   ┌─────────────┐
                   │ Vector Store│ ← Ollama / OpenAI / 硅基流动
                   └─────────────┘
                          │
                          ▼
                    /workspace/ (持久化文件系统)

git clone <repo-url> /opt/memoryfs
cd /opt/memoryfs

cp .env.example .env
nano .env

docker compose up -d --build

# 确认运行状态
docker compose ps
curl http://localhost:${HOST_PORT}/health
# 预期：{"status":"ok","workspace":"/workspace"}

docker compose logs -f                           # 实时日志
docker compose restart                           # 重启服务
docker compose up -d --build                     # 更新重建
docker compose down                              # 停止（数据不丢失）

# 方式一：单 Token（只有一个 Agent 接入时使用）
MCP_TOKEN=your-secret-token

# 方式二：多客户端（多个 Agent 或需要区分角色时使用）
# 启用后 MCP_TOKEN 将被完全忽略，所有 Token 都写进来
# role 支持：admin（可读写）| viewer（只读）
# MCP_CLIENTS='{"your-token-here": {"name": "claude-code", "role": "admin"}, "token-guest": {"name": "guest", "role": "viewer"}}'

EMBED_MODE=grep        # grep（默认，无需外部服务）
                       # vector（需要嵌入 API）
                       # hybrid（grep + vector 融合，效果最佳）
EMBED_URL=http://localhost:11434   # Ollama / OpenAI 兼容服务地址
EMBED_MODEL=nomic-embed-text       # 硅基流动用 BAAI/bge-m3
EMBED_DIMENSIONS=768               # 需与模型匹配
EMBED_API_KEY=                     # Ollama 留空；云端服务填 sk-xxx

ADMIN_USER=admin
ADMIN_PASS=your-admin-password   # 生产环境务必使用 bcrypt 哈希
ADMIN_ENABLED=true               # false 则关闭 /admin 路由
COOKIE_SECURE=false              # 通过 HTTPS 反向代理时设为 true

npm install && npm run hash-password
# 按提示输入密码，复制输出的 $2b$... 哈希值填入 ADMIN_PASS

ADMIN_PASS=$$2b$$10$$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SESSION_TTL=86400000             # 24 小时（默认）
SESSION_CLEANUP_INTERVAL=300000  # 5 分钟（默认）

LOG_LEVEL=info       # 生产用 info，排查问题临时改 debug
LOG_PRETTY=false     # false = JSON（生产）；true = 彩色输出（调试）

{
  "mcp": {
    "servers": {
      "memoryfs": {
        "url": "http://<vm-ip>:<HOST_PORT>",
        "transport": "http",
        "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "memoryfs": {
        "url": "http://memoryfs:3000",
        "transport": "http",
        "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
      }
    }
  }
}

{
  "mcpServers": {
    "memoryfs": {
      "type": "http",
      "url": "http://<vm-ip>:<HOST_PORT>",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

{
  "mcpServers": {
    "memoryfs": {
      "type": "http",
      "url": "http://<vm-ip>:<HOST_PORT>",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

cp /path/to/memoryfs-mcp/scripts/mcp-proxy.mjs ~/mcp-proxy.mjs

{
  "mcpServers": {
    "memoryfs": {
      "command": "node",
      "args": ["/Users/<用户名>/mcp-proxy.mjs"],
      "env": {
        "MEMORYFS_URL": "http://<vm-ip>:<HOST_PORT>",
        "MEMORYFS_TOKEN": "<MCP_TOKEN>"
      }
    }
  }
}

[MemoryFS 一键接入任务]
请按以下步骤帮我接入 MemoryFS 持久化记忆系统，每步完成后报告结果。

服务地址：<SERVER_URL>
我的 Token：<YOUR_TOKEN>

步骤 1 — 写入 MCP 配置
在当前项目的 .mcp.json（若不存在则新建）中写入以下内容：
{
  "mcpServers": {
    "memoryfs": {
      "type": "http",
      "url": "<SERVER_URL>",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

步骤 2 — 验证连接
调用 memory_stats 工具，确认返回知识库统计信息（正常返回即连接成功）。

步骤 3 — 注入行为规范
在当前项目的 AGENTS.md（若不存在则新建）末尾追加以下内容（原样追加，保留格式）：

---
# 记忆库使用规范 (MemoryFS)

你已连接 MemoryFS 持久化外部记忆系统，存储了跨项目的架构决策、经验复盘与技术知识。

1. 先回忆，后行动：遇到问题或新任务前先用 memory_recall 搜索关键词，遭遇报错绝不盲目重试，立刻 recall 错误特征。
2. 按场景分类入库（认知循环：fact→decision→task→reflection→fact）：
   - 稳定技术知识/规范 → fact（importance ≥ 0.7）
   - 架构/行为决策 → decision（importance ≥ 0.85）
   - 踩坑/调试经验/完成任务复盘 → reflection（importance ≥ 0.8）
   - 新项目/服务/人员 → entity
3. 记忆卫生：条目原子化（<500字），title 携带具体特征词，禁止堆栈倾倒。
4. 项目隔离：当前项目存对应 proj，跨项目知识存 global，切换项目调用 project_switch。
5. 决策演进：更新决策时创建新条目并通过 supersedes 指向旧条目，系统自动建立双向链接。
---

完成后，用中文汇报每步操作结果。

# 记忆库使用规范 (MemoryFS)
你已连接到一个被称为 MemoryFS 的持久化外部记忆系统，存储了跨项目的架构决策、行事偏好、历史踩坑与通用规范。必须遵守以下行为逻辑：

1. 先回忆，后重试 (Recall before Retry)
   - 回答问题、生成代码或设计架构前，先用 memory_recall 搜索关键词查阅已有规范。
   - 遭遇工具失败、代码报错或异常行为时，绝对不准盲目重试！立刻对错误特征和核心对象执行
     memory_recall，找寻历史踩坑记录和解决方案。

2. 分类入库（认知循环: fact → decision → task → reflection → fact）
   按以下场景选择类型：
   - 稳定技术知识、设计规范、公司规范 → fact（importance ≥ 0.7）
   - 架构选型、当触发 X → 必须执行 Y → decision（importance ≥ 0.85）
   - 未完成工作、依赖任务 → task
   - 踩坑记录、调试经验、任务完成后复盘 → reflection（importance ≥ 0.8）
   - 项目/服务/人员/外部系统 → entity

   【重要】踩坑记录存 reflection，不存 fact。

3. 记忆卫生 (Hygiene)
   - 条目必须短小、原子化（< 500 字）。
   - title 应携带高度具体的报错特征、函数名或专有名词，保证关键词搜索高命中率。
   - 禁止倾倒原始堆栈、重复结论或对话流水账。

4. 项目隔离与感知 (Scope)
   - 当前项目记忆存入对应 proj，跨项目通用知识存 global。
   - 对话转移到新项目域时，调用 project_switch 切换工作区并获取阻塞任务列表。
   - 不定期调用 memory_stats 审查系统健康度。

5. 决策演进 (Decision Evolution)
   - 更新决策时不修改旧条目，而是创建新条目并通过 supersedes 字段指向被替代的旧条目。
   - 系统会自动将旧条目标记为 superseded 状态，并建立双向链接。
   - 使用 memory_expand 可展开记忆图谱，沿 refs/blocks/supersedes 关系递归追踪依赖链。

{
  type: 'decision' | 'task' | 'fact' | 'entity' | 'reflection',
  title: string,           // 应包含具体关键词便于搜索
  content: string,         // Markdown 正文，建议 < 500 字
  proj?: string,           // 项目名，默认 'global'
  importance?: number,     // 0-1，默认 0.6；踩坑/决策用 0.8+
  confidence?: number,     // 0-1，默认 0.9；置信度
  status?: string,         // 状态（按类型，默认自动填充）
  tags?: string[],         // 可选标签
  blocks?: string[],       // 阻塞的条目 ID
  refs?: string[],         // 关联的条目 ID 数组
  supersedes?: string,     // 被替代的旧条目 ID（用于决策更新）
}

{
  query: string,           // 关键词或语义描述
  limit?: number,          // 最大返回数，默认 10
  proj?: string,           // 按项目过滤
  type?: string,           // 按类型过滤
  force?: boolean          // 强制刷新索引
}

{
  id: string,              // 起始条目 ID
  depth?: number,          // 展开深度，默认 2，最大 5
}

Memory_Data/                # 宿主机目录（MEMORYFS_DATA）
├── memory.md               # 高重要性记忆摘要（热数据）
├── projects.md             # 项目注册表
├── user.md                 # 用户身份与偏好
├── journal/                # 每日操作日志
├── kb/
│   ├── _index.md           # 全局知识索引（缓存，自动维护）
│   ├── decisions/          # 架构与技术决策
│   ├── tasks/              # 任务与里程碑
│   ├── facts/              # 稳定技术知识与规范
│   ├── entities/           # 重要实体配置
│   └── reflections/        # 经验复盘与踩坑记录
├── .sessions/              # Web Admin 会话文件（自动管理）
└── .mcp/
    └── vector.db/          # LanceDB 向量索引（EMBED_MODE=vector/hybrid 时）

# 本地开发（需 Node.js 18+）
npm install
npm run dev            # tsx watch 热重载

# 构建
npm run build

# 测试（289 tests / 9 模块）
npm test
npm run test:coverage  # 生成覆盖率报告（coverage/index.html）

# 生成密码哈希
npm run hash-password