Metadata-Version: 2.4
Name: novelmemo
Version: 0.1.0
Summary: Obsidian-compatible agent memory vault with MCP
Project-URL: Homepage, https://github.com/zyren123/novelMemo
Project-URL: Repository, https://github.com/zyren123/novelMemo
Project-URL: Issues, https://github.com/zyren123/novelMemo/issues
Author: novelmemo contributors
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: agent,jieba,markdown,mcp,memory,obsidian
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: jieba>=0.42
Requires-Dist: mcp>=1.0
Requires-Dist: pyahocorasick>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: watchfiles>=1.0
Description-Content-Type: text/markdown

# novelmemo

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

## 快速开始

### 安装与运行（推荐 uvx）

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

本地开发：

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

### Cursor / MCP 配置示例

在 `mcp.json` 中添加：

```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](https://github.com/salemzack/nocturne_memory) 改编的组件见 [NOTICE](NOTICE)。
