novelmemo 0.1.0

Obsidian-compatible agent memory vault with MCP

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 条记忆。请在 Cursor Rules 或 Agent 系统提示中自行编写 boot 协议（本项目不内置 system prompt）。

CLI

命令	说明
novelmemo init <vault-path>	将 starter vault 模板拷贝到目标目录
novelmemo mcp --vault <path>	启动 MCP stdio 服务

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

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

MCP 工具（6 个）

工具	说明
read_memory(uri)	读取记忆或 system 视图（boot / index / recent / glossary）
create_memory(parent_uri, content, disclosure, title?)	创建子记忆；disclosure 必填，title 可选（支持中文）
update_memory(uri, ...)	patch、append 或更新 disclosure
delete_memory(uri)	删除记忆并同步邻居 Related 段
manage_triggers(uri, add?, remove?)	管理 frontmatter triggers
search_memory(query, domain?, limit?)	FTS + jieba 全文检索

目录结构

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                # sidecar FTS 索引（内部使用）

外部变更同步

当 vault 中的 .md 文件被 MCP 以外的途径修改（例如 git pull）时，后台 watcher 会自动 resync Related 段与 sidecar 全文索引。正常运行时仍以 MCP 写入为主路径。

许可

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