memory-mcp

为智能体管理长期记忆的本地 MCP 服务器。它不把记忆当作「保存了再取出来」的静态存储，而是作为诞生、回想、修订、判定、下沉的生命周期来处理。

核心思路

智能体记忆有两类。有基准（ground truth）的记忆（如代码索引类）只需哈希同步即可；但没有基准的主张型记忆（用户话语、决定、教训）需要状态、版本、可信度、判定门。memory-mcp 将这两者以双重结构结合：

• 原始资料 — 由人阅读、以 git 管理的 Markdown 文件（<store>/memories/*.md，带 frontmatter 元数据）。生命周期状态、supersede 链、可信度都在这里。

• 派生产物 — SQLite 索引（FTS、排序、冲突登记表）。随时可以丢弃，用 memory_reindex 一次就能从原始资料全部重建。

设计综合分析了三个来源（依据追踪见 docs/design/architecture.md 第 12 节）：

Related MCP server: cardloom-mcp

工作原理

remember ──► active ◄─────────── 본문 수정 시 자동 복귀
               │ supersede 되면 자동
               ▼
            archived ──forget(deprecate, reason 필수)──► deprecated
               │                                            │
               └────────── forget(purge, confirm 필수) ──────┘
                            (파일 삭제 — git 이력이 백스톱)

• 冲突叫门：当 memory_remember 检测到相邻记忆时，会把判定材料（共享 entity、时间间隙、latest_wins_eligible）附着在响应中返回。判定是使调用智能体（以及使用者）的职权 —— **没有判定就没有自动覆盖。**已经浮现过的 pair 会被 pairs-hash 记录，不会给两次。

• 风化：旧旧不再使用的记忆不会被删除，而是从排序中慢慢 下沉 —— 公式为 score = text × trust × state × (1 + freshness + heat)。当 memory_status 將老的 episode 提出作为蒸馏（compaction）候选时，智能体会把它摘要成 knowledge 记忆，并对原始记忆执行 supersedes。

• reconcile：没有守护进程。每次工具调用入口都执行 stat 门控（mtime+size）→ sha256 → 索引变更部分。即使徒手改文件，也会在下一次调用时收敛。若直接改抄到 archived 记忆的正文，它会自动回到 active 状态（最新意图优先）。

• 韩语搜索：无需嵌入，查询规划器组合 word FTS（用前缀吸收助词变形）+ trigram FTS（短语）+ 2 字以内 LIKE 回退。「보안을 끄는」↔「보안을 끄고」也能匹配。

• 诚实性：recall/图上"始终报告索引新鲜度、不可解析文件、未解決冲突。无报告 ≠ 完整。

工具（7 个）

安装

Node ≥ 22.5（内置 node:sqlite — 无外部原生依赖）。

pnpm install && pnpm build

登记到 Claude Code：

claude mcp add memory-mcp -- node /path/to/memory-mcp/dist/main.js

或使用 .mcp.json 内：

{
  "mcpServers": {
    "memory-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/main.js"],
      "env": { "MEMORY_MCP_ROOT": "/path/to/your/store" }
    }
  }
}

默认 Store 为 ~/.memory-memory/default ,（可通过环境变量 MEMORY_CP_ROOT 替换，也可按工具的参数切换调用单元）。若把 Store 纳入 git 管理，pip 的后盾就是 git 历史。

记忆文件格式

---
id: 01JD2K3A9FZQ4W8XVBH5T6N7RM
type: fact | preference | decision | episode | reference | knowledge
state: active | archived | deprecated
trust: user-stated | agent-inferred | imported
entities: [ads-genisys, pacing]
source: "2026-08-24 세션, 사용자 교정"
created: 2026-08-24T14:03:00Z
updated: 2026-08-24T14:03:00Z
review_after: 2026-11-01
---
# 제목 한 줄

본문. 첫 문단이 recall 발췌로 쓰인다.

另外放置 <store>/dictionary.md 即可规范化 entity 标记法（- 正式名称: 说明 (aka: 同义词, 缩写)）。

ски开发

pnpm typecheck   # tsc --noEmit
pnpm test        # node --test (29 tests)
pnpm lint        # biome
pnpm build       # dist/

文档

• 设计：docs/design/architecture.md — 原理、状态机、来源→决定追踪表

• 分析：codebase-memory-mcp 实测 · Codebase-Memory 论文 · MemOS 论文

License