Obsidian AI Cortex MCP

黑曜石AI Cortex 2.0

MCP（模型上下文协议）服务器，为AI代理提供对黑曜石保管库的直接文件系统访问，不需要黑曜岩应用程序。围绕轻量级内存系统构建，让代理在会话之间维护持久上下文。

它的作用

Obsidian AI Cortex公开了8个类别的17个工具，涵盖了从阅读和书写笔记到搜索、管理前台和恢复会话内存的所有内容。核心是 vault_recall --一个单一的调用工具，旨在在每个会话开始时恢复AI代理的工作上下文。

需求

• Node.js>=18
• 黑曜石保险库（或任何Markdown文件文件夹）

安装

git clone https://github.com/tcurtsinger/Obsidian-AI-Cortex-MCP.git
cd Obsidian-AI-Cortex-MCP
npm install
npm run build

配置

设置一个环境变量：

OBSIDIAN_VAULT_PATH=/path/to/your/vault

传递给工具的所有注释路径都是相对于此根的。

运行服务器

# Production
OBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.js

# Watch mode (development)
npm run dev

服务器通过stdio进行通信，并与任何MCP客户端（Claude Desktop、Claude Code等）兼容。

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/Obsidian-AI-Cortex-MCP/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

克劳德代码(.mcp.json)

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/Obsidian-AI-Cortex-MCP/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

______________________________________________________________________

工具参考

阅读

vault_read

读一个便条。返回内容和可选解析的frontmatter。

vault_batch_read

一次通话最多可阅读20个笔记。读取并行运行。

______________________________________________________________________

写

vault_write

创建或更新笔记。支持覆盖、追加和预置模式。

vault_append

使用可配置的分隔符将内容添加到注释中。如果注释不存在，则创建注释。

vault_delete

从vault中删除注释。

vault_move

移动或重命名注释。如果目标已存在，则失败。

______________________________________________________________________

搜索

vault_search

在所有笔记中进行全文搜索。支持纯文本或正则表达式。每个文件最多返回5行匹配行。

vault_find_by_tag

通过frontmatter标签查找笔记。支持或(any)或与(all)匹配。

vault_recent

查找最近修改的笔记。

______________________________________________________________________

结构

vault_list

列出vault目录中的文件和文件夹。

vault_tree

将vault的文件夹/文件树作为嵌套结构获取。

______________________________________________________________________

元数据

vault_frontmatter

在笔记上获取、设置或合并YAML frontmatter。

• set --将所有正面内容替换为 data
• merge --合并 data 进入现有前沿

vault_upsert_section

通过标题插入或替换标记部分。如果标题存在，则替换其内容。如果它不存在，则将其附加。

vault_backlinks

通过以下方式查找链接到特定笔记的所有笔记 [[wiki-links]].按文件名和完整路径匹配，包括别名链接。

______________________________________________________________________

每日笔记

vault_daily_note

获取或创建每日笔记。如果模板不存在，则从模板创建注释。

未提供默认模板时：

# YYYY-MM-DD

## Tasks

- [ ]

## Notes

______________________________________________________________________

统计

vault_stats

获取vault统计信息：文件计数、封面覆盖率、活动和顶部标签。

退货：

• 文件数量和总大小
• 正面广告和标签覆盖率
• 活动总结（最近7天修改/超过90天失效）
• 按频率排列的前10个标签
• 健康评估（正面报道、过时内容、最近活动）

______________________________________________________________________

记忆/回忆

vault_recall

为活动项目加载AI工作内存。这是存储系统的核心。

它是如何工作的：

1. 如果 project_path 如果提供，则直接加载该文件。
2. 否则，阅读 _Context/Now.md 和提取物 active_project_context 从其正面来看。
3. 加载项目的 _Context.md 并将其与路由器元数据一起返回。
4. 可选地包括用于压实后恢复的压实面包屑。

典型的代币成本：约300-500个代币。

______________________________________________________________________

存储器系统

内存系统是建立在这些工具之上的一种固执己见的模式。它为AI代理提供了跨会话和上下文压缩事件的持久、项目范围的工作内存。

结构

_Context/
  Now.md              ← Router: which project is active
  _LastCompaction.md  ← Safety breadcrumb written before compaction
Work/Projects/
  My Project/
    _Context.md       ← Per-project memory: state, decisions, next steps

_Context/Now.md

在其前体中具有单个密钥的路由文件：

---
active_project_context: Work/Projects/My Project/_Context.md
---

当 vault_recall 调用时不带参数，它读取此文件以发现哪个项目处于活动状态，然后加载该项目的 _Context.md.

_Context.md （每个项目）

一个自由格式的markdown文件，用作代理对项目的工作记忆。推荐章节：

## Current State
What's done, what's in progress.

## Decisions
Key architectural or design choices made.

## Blockers
What's stuck and why.

## Next Steps
Concrete next actions.

在每个会话结束时使用以下命令更新此文件 vault_upsert_section 因此，下一节课可以无缝衔接。

______________________________________________________________________

克劳德代码挂钩

这 hooks/ 该目录包含用于Claude Code生命周期钩子的shell脚本。从以下位置复制钩子命令 hooks/settings.json 进入你的 ~/.claude/settings.json 以使他们能够。

会话开始注射

当克劳德代码开始时， session-start.sh 读取 _Context/Now.md 找到活动项目并注入以下消息：

MEMORY SYSTEM ACTIVE — Project: Work/Projects/My Project/_Context.md
Call vault_recall() immediately to load your working memory before doing anything else.

这会提示代理呼叫 vault_recall() 在执行任何其他操作之前，请在单个工具调用中恢复完整的项目上下文。

CLAUDE.md集成

将此添加到您的 CLAUDE.md 连接存储系统：

## Session Start
When you see "MEMORY SYSTEM ACTIVE", call `vault_recall()` immediately before doing anything else.

## During Work
After completing meaningful work, update the project's `_Context.md` via `vault_upsert_section`.

## Session End
Update the project's `_Context.md` with final state so the next session can pick up seamlessly.

______________________________________________________________________

发展

# Build TypeScript
npm run build

# Watch mode
npm run dev

源布局：

src/
  index.ts              Entry point, server setup
  types.ts              Shared response helpers (ok/err)
  helpers/
    files.ts            Filesystem utilities
    markdown.ts         Section upsert logic
    notes.ts            Note read/write helpers
    paths.ts            Path normalization
  tools/
    read.ts             vault_read, vault_batch_read
    write.ts            vault_write, vault_append, vault_delete, vault_move
    search.ts           vault_search, vault_find_by_tag, vault_recent
    structure.ts        vault_list, vault_tree
    metadata.ts         vault_frontmatter, vault_upsert_section, vault_backlinks
    daily.ts            vault_daily_note
    stats.ts            vault_stats
    recall.ts           vault_recall

许可证

麻省理工学院