mnemograph

Mnemograph

面向 AI 编码 Agent 的持久化事件溯源知识图谱。与简单的键值记忆不同，Mnemograph 会记录实体、关系和观察，从而支持语义搜索、分层上下文检索，以及基于 Git 的 AI 记忆版本控制。

兼容：Claude Code、opencode、codex CLI、Zed、Continue.dev，以及任何兼容 MCP 的 Agent。

为什么选择 Mnemograph？

AI 编码会话是短暂的。Mnemograph 为你的 AI 伙伴提供持久记忆，可以：

• 跨会话留存 — 持续保存决策、模式和经验
• 支持语义搜索 — 按含义而非仅按关键词查找相关上下文
• 提供分层检索 — 根据需要，从浅层摘要到深层子图
• 像代码一样进行版本控制 — 对知识图谱执行分支、提交、差异比较和还原
• 支持协作 — 在用户或项目之间共享记忆仓库

记忆范围：本地与全局

使用 mnemograph 前，请决定记忆的存储位置：

范围	路径	适用场景
项目本地	./.claude/memory	仅适用于此仓库的知识（架构、决策、模式）
全局	~/.claude/memory	跨项目知识（个人经验、通用模式、偏好）
自定义	通过 MEMORY_PATH 指定任意路径	团队共享记忆、组织范围的知识库

重要提示： 首次为项目设置 mnemograph 时，Agent 应询问用户要使用哪种范围。这会影响知识的存储位置，以及是否在多个项目之间共享。

# Project-local (default)
MEMORY_PATH=".claude/memory"

# Global (cross-project)
MEMORY_PATH="$HOME/.claude/memory"

# CLI: use --global flag
mnemograph --global status
mnemograph --global graph

快速开始

选项 1：让 Claude Code 安装

将此仓库 URL 提供给 Claude Code，并让它设置 mnemograph：

https://github.com/tm42/mnemograph

也可以直接将设置说明发给 Claude：

Read https://raw.githubusercontent.com/tm42/mnemograph/main/SETUP_CLAUDE_CODE.md and follow them

选项 2：手动安装

# Install from PyPI
pip install mnemograph

# Add to Claude Code (global, available in all projects)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uvx mnemograph

# Initialize memory directory
mkdir -p ~/.claude/memory

选项 3：其他 MCP 客户端

每种 MCP 客户端的配置格式都不同。参阅 UNIVERSAL_MCP_COMPATIBILITY.md，获取以下客户端的可直接复制配置：

• opencode — ~/.config/opencode/opencode.json
• Codex CLI — ~/.codex/config.yaml
• Zed — ~/.config/zed/settings.json
• Continue.dev — ~/.continue/config.json

关键环境变量是 MEMORY_PATH — 将其设置为你希望存储知识图谱的位置。

选项 4：从源代码安装

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync

# Add to Claude Code (or adapt for your MCP client)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uv run --directory /path/to/mnemograph mnemograph

用法

MCP 工具（供任何 Agent 使用）

Mnemograph 通过 MCP 提供以下工具：

核心操作：

工具	描述
remember	主要存储工具：以原子方式存储知识（一次调用即可存储实体、观察和关系）
recall	主要检索工具：获取相关上下文并自动管理令牌。使用 focus=['Entity'] 获取完整详情。默认输出为易读的散文文本。
create_entities	创建实体（匹配度 >80% 时自动阻止重复项）
create_relations	使用带类型的边连接实体（implements、uses、decided_for 等）
add_observations	为现有实体添加事实或备注
read_graph	获取完整知识图谱（警告：内容可能很大）
delete_entities	删除实体（级联删除相关关系）
delete_relations	删除指定关系
delete_observations	删除指定观察

会话生命周期：

工具	描述
session_start	发出会话开始信号，获取初始上下文。返回 quick_start 指南。
session_end	发出会话结束信号，可选择保存摘要
get_primer	了解知识图谱概况（在会话开始时调用）

分支（并行工作流）：

工具	描述
create_branch	创建用于隔离工作的命名分支（例如 "feature/auth-refactor"）
switch_branch	切换到其他分支
list_branches	列出所有分支
merge_branch	将分支合并到 main
delete_branch	删除分支
get_current_branch	获取当前分支名称

图谱维护：

工具	描述
find_similar	查找名称相似的实体（重复项检测）
find_orphans	查找没有关系的实体
merge_entities	合并重复实体（整合观察并重定向关系）
get_graph_health	评估图谱质量：孤立实体、重复项、过载实体
suggest_relations	根据语义相似度建议潜在关系
create_entities_force	创建实体并跳过重复项检查
clear_graph	清除所有实体和关系（基于事件溯源，可回退）

时间回溯：

工具	描述
get_state_at	查看历史中任意时间点的图谱状态
diff_timerange	显示两个时间点之间的变化
get_entity_history	查看指定实体的完整变更日志
rewind	使用 git 将图谱回退到之前的状态
restore_state_at	将图谱恢复到指定时间戳的状态（保留审计记录）
reload	从磁盘重新加载图谱状态（git 操作后使用）

边权重：

工具	描述
get_relation_weight	获取权重明细（近期性、共同访问、显式权重）
set_relation_importance	设置显式重要性权重（0.0-1.0）
get_strongest_connections	查找实体最重要的关联
get_weak_relations	查找可供剪枝的候选关系（低权重关系）

Recall：散文格式与图谱格式

recall 工具默认以散文格式返回上下文——可直接供 Agent 使用、无需解析 JSON 的易读文本：

# Default: prose format (human-readable)
recall(depth="medium", query="authentication")
# Returns:
# **MyApp** (project)
# A Python web service. Uses OAuth2 for user auth.
# Uses: PostgreSQL, Redis
#
# **Decisions:**
# • Decision: Use JWT — Stateless tokens for API authentication
#
# **Gotchas:**
# • Token expiry is 1 hour by default
# • Refresh tokens stored in Redis

# Optional: graph format (structured JSON)
recall(depth="medium", query="authentication", format="graph")

深度级别：

• shallow — 快速摘要：实体数量、近期活动、注意事项
• medium — 语义搜索 + 1 跳邻居（约 2000 个令牌）
• deep — 从聚焦实体开始进行多跳遍历（约 5000 个令牌）

**注意事项提取：**以 Gotcha:、Warning:、Note: 或 Important: 开头的观察会自动提取到专门的部分。

CLI 工具

mnemograph — 用于所有记忆操作的统一 CLI：

# Basic operations
mnemograph status                # Show entity/relation counts, recent events
mnemograph log                   # View event history
mnemograph log --session X       # Filter by session
mnemograph sessions              # List all sessions
mnemograph export                # Export graph as JSON

# VCS commands (git-based version control)
mnemograph vcs init              # Initialize memory as git repo
mnemograph vcs commit -m "msg"   # Commit current state
mnemograph vcs log               # View commit history
mnemograph vcs revert --event ID # Undo specific events (compensating events)
mnemograph vcs revert --session X # Undo entire session

# Graph visualization
mnemograph graph                 # Open interactive graph viewer
mnemograph graph --watch         # Live reload mode (refresh button)

# Time travel
mnemograph show --at "2 days ago"  # View state at a point in time
mnemograph diff "1 week ago"       # Show changes since then
mnemograph history "EntityName"    # Full changelog for an entity
mnemograph rewind -n 1             # Git-based rewind by N commits
mnemograph restore --to "yesterday" # Event-based restore (audit-preserving)

# Graph health and maintenance
mnemograph health                # Show graph health report (orphans, duplicates, etc.)
mnemograph health --fix          # Interactive cleanup mode
mnemograph similar "React"       # Find entities similar to "React" (duplicate check)
mnemograph orphans               # List entities with no relations
mnemograph suggest "FastAPI"     # Suggest relations for an entity
mnemograph clear                 # Clear all entities and relations (with confirmation)

# Global options (come *before* the subcommand)
mnemograph --global status       # Use global memory (~/.claude/memory)
mnemograph --memory-path /path graph  # Custom memory location

在任何位置运行（无需激活 venv）：

# Using uv (recommended)
uv run --directory /path/to/mnemograph mnemograph graph

# Using uvx (if installed from PyPI)
uvx --from mnemograph mnemograph status

图谱可视化 — 交互式 D3.js 查看器：

• 布局算法：力导向、径向（枢纽位于中心）、聚类（按组件分组）
• 颜色模式：按实体类型、连通分量或度中心性着色
• 边权重滑块：按连接强度筛选连接
• 实时刷新：--watch 模式带有 Refresh 按钮，可实时更新

架构

~/.mnemograph/memory/    # or ~/.claude/memory, ~/.opencode/memory, etc.
├── mnemograph.db        # SQLite database (events + vectors)
├── state.json           # Cached materialized state (derived)
└── .git/                # Version history

事件溯源意味着所有变更都会作为不可变事件记录在 SQLite 中。当前状态通过重放事件计算得出。这使得以下功能成为可能：

• 完整记录所有变更历史
• 撤销任何操作
• 对知识图谱进行分支和合并
• 审计 Claude 学到了什么以及何时学到

两层版本控制：

• mnemograph vcs revert — 细粒度，通过补偿事件撤销特定事件
• mnemograph rewind / mnemograph restore — 粗粒度，按 git 级别或时间戳恢复

分支

分支让你可以在隔离的知识上进行工作，而不影响主图谱。适用于：

• 探索性工作 — 尝试不同方法，而不污染共享知识
• 特定功能的上下文 — “feature/auth-refactor”将身份验证决策分开保存
• 多个项目 — 在不同代码库之间切换上下文

创建和使用分支

# Create a branch for your feature
create_branch(name="feature/auth-refactor")

# Work normally — all operations happen on this branch
remember(name="OAuth2", entity_type="concept",
         observations=["Implementing OAuth2 flow"])

# Switch back to main to see clean state
switch_branch(name="main")

# Merge when ready
merge_branch(source="feature/auth-refactor", target="main")

分支的工作方式

• 主分支始终存在，包含共享知识
• 功能分支继承自主分支，但新增内容保持隔离
• 自动筛选 — recall、search 等仅查看当前分支和主分支
• 合并会将分支中的实体/关系复制到目标分支
• 删除会在合并后清理内容（或放弃探索性工作）

分支命名约定

模式	用途
feature/xyz	特定功能的知识
explore/xyz	探索性/实验性工作
project/xyz	特定项目的上下文
user/name	个人工作区

实体类型

类型	用途	示例
concept	想法、模式、方法	“Repository pattern”、“Event sourcing”
decision	带有理由的选择	“为求简单，选择 SQLite 而非 Postgres”
project	代码库、系统	“auth-service”、“mnemograph”
pattern	重复出现的代码模式	“使用 Result 类型进行错误处理”
question	尚未解决的问题	“我们应该添加实时同步吗？”
learning	发现	“pytest fixtures 可简化测试设置”
entity	通用（人员、文件等）	“Alice”、“config.yaml”

主题约定

使用主题实体作为浏览相关知识的入口：

# Create topic entry points
create_entities([
    {"name": "topic/projects", "entityType": "entity"},
    {"name": "topic/decisions", "entityType": "entity"},
    {"name": "topic/patterns", "entityType": "entity"},
])

# Link entities to their topics
create_relations([
    {"from": "auth-service", "to": "topic/projects", "relationType": "part_of"},
    {"from": "Decision: Use Redis", "to": "topic/decisions", "relationType": "part_of"},
])

标准主题：

• topic/projects — 项目实体
• topic/decisions — 架构决策
• topic/patterns — 模式和实践
• topic/learnings — 重要发现
• topic/questions — 未解决的问题

这样就可以通过浏览 topic/decisions，轻松查询“我们做过哪些决策？”

开发

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync                    # Install dependencies
uv run pytest --cov        # Run tests with coverage (enforces 75% minimum)
uv run ruff check .        # Lint
uv run mnemograph          # Run MCP server directly

基于

Mnemograph 基于 MCP server-memory 构建 — Anthropic 的官方记忆服务

许可证

MIT