# agent-memory-base-obsidian

**Repository Path**: hujunwei-dev/agent-memory-base-obsidian

## Basic Information

- **Project Name**: agent-memory-base-obsidian
- **Description**: 基于obsidian的agent全局记忆系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Obsidian Memory — 跨 Agent 共享的个人记忆系统

一个基于 Obsidian vault 的私人语义记忆图谱。markdown 是唯一真相源，SQLite + FTS5 派生索引就地重建，薄 MCP server 提供检索。任何 MCP 兼容的 AI agent 零胶水接入，换机器同步即无缝切换。

```
你的任何 AI agent（Claude Code / OpenCode / Hermes / OpenClaw / Codex / DeepSeek）
        │
        │  MCP 协议（stdio）
        ▼
┌─────────────────────────────────────────┐
│  memory_mcp.py  (薄 MCP server)          │
│  工具: search / read_note / write_note   │
│        backlinks / graph                 │
├─────────────────────────────────────────┤
│  三路召回: FTS 关键词 + 向量语义 + 图遍历  │
│  融合: Reciprocal Rank Fusion            │
├─────────────────────────────────────────┤
│  源（同步）              派生（本地重建） │
│  markdown 笔记 + FM  ──→ SQLite 索引      │
│  MEMORY.md 常驻索引  ──→ 向量索引(可选)   │
│  skills/ 程序记忆    ──→ links 图         │
└─────────────────────────────────────────┘
```

## 快速开始（3 步）

### 1. 克隆并作为 Obsidian vault 打开

```bash
git clone https://gitee.com/你的用户名/obsidian-memory.git
```
打开 Obsidian → 「打开文件夹作为仓库」→ 选 `obsidian-memory` 目录。这就是你的新 vault 了。

### 2. 安装依赖并建索引

```bash
cd obsidian-memory
python .memory/server/bootstrap.py
```
这会装好 MCP SDK 并扫描 vault 建立 SQLite 索引。完成后出现 `.memory/index.db`（派生产物，已被 gitignore，不同步）。

### 3. 接入你的 AI agent

在对应 agent 的 MCP 配置里加一行指向 server（见下方各 agent 说明）。重启 agent 即可使用 `search` / `write_note` 等记忆工具。

---

## 接入各 AI Agent

所有 agent 都通过 **stdio MCP 协议**接入，核心配置都是「command + args 指向 `memory_mcp.py`」。`${VAULT}` 替换为你的 vault 绝对路径。

### Claude Code

项目根目录 `.mcp.json`（已含模板）或全局 `~/.claude.json`：

```json
{
  "mcpServers": {
    "obsidian-memory": {
      "command": "python",
      "args": ["/你的路径/obsidian-memory/.memory/server/memory_mcp.py"]
    }
  }
}
```
首次启动会问是否信任此项目的 MCP server，选信任。

### OpenCode

`opencode.jsonc` 的 `mcp` key（command 是数组形式）：

```jsonc
{
  "mcp": {
    "obsidian-memory": {
      "type": "local",
      "command": ["python", "/你的路径/obsidian-memory/.memory/server/memory_mcp.py"],
      "enabled": true
    }
  }
}
```

### Hermes

`~/.hermes/config.yaml` 的 `mcp_servers`：

```yaml
mcp_servers:
  obsidian-memory:
    command: "python"
    args: ["/你的路径/obsidian-memory/.memory/server/memory_mcp.py"]
```
> 也可用 `hermes import-agent claude-code` 一键迁移 Claude Code 的配置。

### OpenClaw

基于 Claude Code 协议，配置同 Claude Code 的 `.mcp.json` 格式。

### Codex CLI ⚠️ 待核实

`~/.codex/config.toml`，格式推断如下（以官方文档为准：<https://learn.chatgpt.com/docs/codex/extend/mcp>）：

```toml
[mcp_servers.obsidian-memory]
command = "python"
args = ["/你的路径/obsidian-memory/.memory/server/memory_mcp.py"]
```

### DeepSeek Harness ⚠️ 待核实

DeepSeek Harness 处于 developer preview，原生 MCP 配置方式尚未明确。
**已确认可行的替代方案**：DeepSeek API 可作为后端模型接入 Claude Code / OpenCode，即用它们的壳 + DeepSeek 模型 + 本记忆系统的 MCP，无需等 Harness 原生支持。

> 各 agent 的完整配置样例文件在 `.memory/config-samples/` 目录。

---

## 记忆类型

通过 frontmatter 的 `metadata.type` 区分，对应五种模板（在 `.memory/templates/`）：

| type | 存什么 | 何时用 |
|---|---|---|
| `user` | 角色 / 偏好 / 知识背景 | 让 agent 了解你是谁 |
| `feedback` | 纠正过或验证过的做法 | 避免重复犯错、复用好做法 |
| `project` | 进行中的工作 / 目标 / deadline | 给当前任务上下文 |
| `reference` | 指向外部系统的指针 | 知道去哪查信息 |
| `tool` | 工具安装 / 配置 / 用法 | 复用工具经验 |

## MCP 工具

agent 接入后获得 5 个工具：

| 工具 | 作用 | 何时用 |
|---|---|---|
| `search(query, type?, limit?)` | 三路召回，返回压缩卡片（省上下文） | 大多数场景，先搜再看 |
| `read_note(path)` | 读单篇笔记全文 | 搜到卡片后需要详情时（深加载） |
| `write_note(path, content, mtype, ...)` | 写笔记，自动维护 frontmatter + 索引 + MEMORY.md | 沉淀新经验时 |
| `backlinks(slug)` | 查谁通过 `[[wikilink]]` 链接到本笔记 | 理解关联关系 |
| `graph(slug, depth?)` | 取邻接子图（节点+边） | 理解知识网络结构 |

## 三层记忆模型（解决上下文长度）

- **常驻层** `MEMORY.md`：全局核心，agent 默认加载（上限 ~200 行）。放"你是谁""当前在做什么"这类必须一直知道的事。
- **自动召回层**：进入某场景时 `search` 自动召回相关记忆卡片（压缩的，只含标题+描述+元数据）。
- **按需深加载层**：任务中碰到相关话题时 `search(include_body=True)` 或 `read_note` 拉取全文，用完即弃。

上下文里永远只有「此刻相关」的记忆，其余躺在 vault 里零成本。

## 向量检索（可选，默认关闭）

纯 FTS + 图遍历已够用。词汇开始发散（"资金划拨"vs"转账"）时启用语义检索：

```bash
pip install fastembed sqlite-vec
# 设环境变量
set OBSIDIAN_VECTOR=1          # Windows
export OBSIDIAN_VECTOR=1       # Linux/Mac
python .memory/server/rebuild_index.py
```

中文语义模型 `BAAI/bge-small-zh-v1.5`（~95MB，CPU 可跑，无需 ollama / GPU / API）。

## 记忆巩固（自我进化）

```bash
python .memory/server/consolidate.py              # 近 30 天 feedback
python .memory/server/consolidate.py --days 60    # 自定义窗口
python .memory/server/consolidate.py --type project
```

聚类同类记忆，合成更高层规律，输出**提案**到 `.memory/proposals/` 待你审阅。认可的在 Obsidian 里完善后转为正式记忆，不认可的删除。这是有边界的进化——提案必须经你批准才成为承重记忆，防止幻觉积累。

## 换机器 / 多机同步

```
新机器: git clone → python .memory/server/bootstrap.py → 完成
```
派生索引（`index.db`）不同步，每台机器就地重建。所有源数据在 markdown 里，跟着 git 走。

## 敏感数据

`memory_mcp.py` 里的 `SENSITIVE_PATTERNS` 匹配的文件不索引、不嵌入、search 不返回。默认含 `*token*` / `.env` / `*secret*` / `*credential*`。源文件仍在 vault，只是检索看不到。按需自行调整。

## 目录结构

```
obsidian-memory/
├── .mcp.json                    # Claude Code / OpenClaw 的 MCP 配置
├── MEMORY.md                    # 常驻记忆索引（agent 默认加载）
├── 记忆库/                       # 你的记忆笔记放这里（示例目录，可自建）
├── .memory/
│   ├── server/
│   │   ├── memory_mcp.py        # MCP 服务本体
│   │   ├── rebuild_index.py     # 全量重建索引
│   │   ├── bootstrap.py         # 新机器一键装依赖+建索引
│   │   ├── consolidate.py       # 记忆巩固/进化
│   │   └── requirements.txt
│   ├── templates/               # 五种 frontmatter 模板
│   ├── config-samples/          # 各 agent 的接入配置样例
│   ├── proposals/               # 巩固提案（待审）
│   ├── skills/                  # 跨 agent 共享的 SKILL.md
│   └── .gitignore               # 排除 index.db 等派生产物
└── .gitignore
```

## 设计原则

1. **markdown 是唯一真相源** — MCP 只是访问层；不支持 MCP 的 agent 能裸文件降级
2. **薄中间层** — 拒绝纯裸文件（规模化后检索崩塌）和重型图数据库（丢人可读性），选薄 MCP server
3. **派生数据就地重建** — 索引不同步，新机器 `bootstrap.py` 重建，避免二进制冲突
4. **有边界的进化** — 巩固产出提案待审，批准才成承重记忆，防幻觉
5. **路径自适应** — 零配置，clone 即用，无需改硬编码路径

## 许可

MIT