novelmemo

面向 AI Agent 的长期记忆 MCP 服务：将记忆持久化为 Obsidian 兼容的 Markdown vault，供 Agent 读写、供 Obsidian 只读可视化记忆图谱。

快速开始

安装与运行（推荐 uvx）

uvx novelmemo init ~/my-vault
uvx novelmemo mcp --vault ~/my-vault

本地开发：

uv sync
uv run novelmemo init ./my-vault
uv run novelmemo mcp --vault ./my-vault

Cursor / MCP 配置示例

在 mcp.json 中添加：

{
  "mcpServers": {
    "novelmemo": {
      "command": "uvx",
      "args": ["novelmemo", "mcp", "--vault", "/path/to/my-vault"]
    }
  }
}

工作流约定

• MCP 是唯一写入方：记忆的创建、更新、删除以及 ## Related memories 自动链接段均由 MCP 维护。
• Obsidian 只读使用：在 Obsidian 中打开 vault 浏览图谱与正文，请勿手改记忆文件；.memory/ 目录（sidecar 索引与配置）可加入 Obsidian ignore。
• 会话起始：在新 Agent 会话中调用 read_memory("system://boot") 加载 memory.yaml 中配置的 boot 记忆；boot 视图末尾会附加最近修改的 5 条记忆。novelmemo 通过 MCP 提供工具但不推送使用说明，boot 加载与读写时机等主动行为需由 Agent 系统提示驱动——可直接采用 docs/system-prompt.md，粘进 Cursor Rules 或 Agent 系统提示即可。

Agent benchmark

仓库内置 18 个版本化场景，分别评测 Agent 对已有记忆的自主使用和跨会话的记忆形成—召回闭环，并比较 no-memory、boot-only、search-only、full-agent 四种条件。运行方法、质量门槛与结果解释见 docs/agent-benchmark.md。 评测分为 Product profile（默认，使用项目正式 system prompt，仅运行 full-agent）和 Ablation profile（使用中立提示词比较四种记忆条件）。 P0 v1.0.1 的开发与 held-out 结果、有效性审计和可对外陈述边界见 docs/agent-benchmark-results-v1.0.1.md。

CLI

业务配置位于 {vault}/.memory/memory.yaml（valid_domains、boot_uris、locale 等）。优先级：CLI > 环境变量 > memory.yaml > 默认值。

环境变量（v1）：MEMORY_BOOT_URIS、MEMORY_VALID_DOMAINS、MEMORY_LOCALE。

MCP 工具（6 个）

目录结构

my-vault/
  core/agent/_index.md      → core://agent
  core/my_user.md           → core://my_user
  writer/characters/爱丽丝.md → writer://characters/爱丽丝
  .memory/
    memory.yaml             # 业务配置
    index.db                # 可重建的 FTS + RelatedGraph sidecar（内部使用）

外部变更同步

当 vault 中的 .md 文件被 MCP 以外的途径修改（例如 git pull）时，后台 watcher 会按变化路径增量同步 Related 段与 sidecar 索引。搜索和普通单条写入不扫描整个 vault；sidecar 缺失或状态不一致时会从 Markdown 自动重建。正常运行时仍以 MCP 写入为主路径。

开发者可用 uv run novelmemo-perf --json result.json --markdown result.md 复现 100/1,000/10,000 条短记忆的初始化、rebuild、热搜索和 CRUD 基准。仓库基线见 docs/performance/incremental-related-graph.md。

许可

MIT License。自 Nocturne Memory 改编的组件见 NOTICE。