Skip to main content
Glama
deenesjakoruzh
jmjava

obsidian-dev-memory

by jmjava
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Obsidian 开发者记忆 MCP

一个本地 Model Context Protocol 服务器，为 Cursor 和 GitHub Copilot 等 AI 编码助手提供持久化的工程记忆。

记忆以普通 Markdown 文件的形式存储在 Obsidian 仓库中。Obsidian 无需运行。没有社区插件，也不需要 Obsidian API 密钥。

同一个 stdio MCP 服务器可同时用于 Cursor 和 GitHub Copilot / VS Code。

架构

Cursor Agent --------------------\
                                  \
                                   > MCP stdio server
                                  /        |
GitHub Copilot / VS Code --------/         v
                               obsidian-dev-memory
                                        |
                                        v
                               Obsidian Markdown Vault
Developer opens spring-auth in Cursor
        |
        v
Cursor calls get_project_context("spring-auth")
        |
        v
AI sees current project state + recent decisions
        |
        v
Developer and AI implement feature
        |
        v
AI calls capture_work_session(...)
        |
        +--> session note
        |
        +--> Git branch/SHA recorded
        |
        v
Durable architecture choice?
        |
       yes
        |
        v
record_decision(...)

Related MCP server: LumenCore

为什么直接使用 Markdown？

仓库是事实来源。笔记可以在 Obsidian、git 或任何文本编辑器中阅读和编辑。服务器从不依赖 Obsidian 处于打开状态，从不与托管的记忆 API 通信，也从不写入专有数据库。

要求

  • Python 3.12+

  • uv

  • 一个本地 Obsidian 仓库目录

  • 仅当您需要自动仓库快照时，才需要在 PATH 上安装 Git

安装

git clone https://github.com/jmjava/obsidian-mcp.git
cd obsidian-mcp
uv sync

uv sync 会安装官方的 MCP Python SDK 和项目包。

配置

必需：

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"

可选：

export OBSIDIAN_MEMORY_ROOT="AI Memory"

OBSIDIAN_MEMORY_ROOT 默认为 AI Memory。编辑器 MCP 配置可以直接提供这些变量。本项目包含 .env.example 作为文档参考；服务器不会自动加载 .env 文件。

运行服务器

export OBSIDIAN_VAULT_PATH="/tmp/example-vault"
mkdir -p "$OBSIDIAN_VAULT_PATH"

uv run python -m obsidian_dev_memory

或者：

uv run obsidian-dev-memory

该进程通过 stdio 使用 MCP 协议通信。请勿将应用程序日志写入 stdout；诊断信息应输出到 stderr。

Cursor 设置

项目级 Cursor 配置位于 .cursor/mcp.json，使用当前的 mcpServers 格式。可移植模板位于 config/cursor.mcp.json.example：

{
  "mcpServers": {
    "obsidian-dev-memory": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/obsidian-dev-memory-mcp",
        "run",
        "python",
        "-m",
        "obsidian_dev_memory"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/ABSOLUTE/PATH/TO/OBSIDIAN/VAULT"
      }
    }
  }
}

本仓库还附带 .cursor/rules/obsidian-memory.mdc，用于告知 Cursor 何时读写记忆。

特定机器的 .cursor/mcp.json 文件由安装程序创建，不会提交到此处。

GitHub Copilot / VS Code 设置

工作区 Copilot / VS Code 配置位于 .vscode/mcp.json，使用当前的 servers 格式。可移植模板位于 config/vscode.mcp.json.example：

{
  "servers": {
    "obsidian-dev-memory": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/obsidian-dev-memory-mcp",
        "run",
        "python",
        "-m",
        "obsidian_dev_memory"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/ABSOLUTE/PATH/TO/OBSIDIAN/VAULT"
      }
    }
  }
}

.github/copilot-instructions.md 为 Copilot 提供与 Cursor 相同的记忆行为。

安装程序用法

将此服务器接入另一个开发项目：

./scripts/install-project.sh \
  --project /home/user/src/example \
  --vault /home/user/Documents/ObsidianVault

可选：

./scripts/install-project.sh \
  --project /home/user/src/example \
  --vault /home/user/Documents/ObsidianVault \
  --server /path/to/obsidian-dev-memory-mcp

如果省略 --server，脚本会根据自身位置推断本仓库。

安装程序会创建或更新：

  • <project>/.cursor/mcp.json

  • <project>/.cursor/rules/obsidian-memory.mdc

  • <project>/.vscode/mcp.json

  • <project>/.github/copilot-instructions.md

当目标项目或仓库不存在时，它会明确报错，并且会合并 MCP JSON，以免破坏无关的服务器。

MCP 工具

工具

用途

get_project_context

读取 Project State.md 以及最新的会话和决策笔记

capture_work_session

向今天的会话笔记追加一个带时间戳的章节

record_decision

写入一条持久的决策笔记

update_project_state

替换简洁的项目状态笔记

search_memory

对项目记忆进行本地文件名和文本搜索

read_note

读取一个仓库相对路径的 Markdown 文件

append_daily_note

追加到 Daily/YYYY-MM-DD.md

当项目是新建的时，get_project_context 返回空章节而不是报错。

record_decision 写入 YYYY-MM-DD-<decision-slug>.md。如果该文件已存在，服务器会添加数字后缀（-2、-3、……）而不是覆盖。

capture_work_session 接受可选的 repository_path。当该路径是 Git 仓库时，笔记会记录仓库名称、分支、短 SHA、脏状态和简短的已更改文件列表。绝不会写入完整的差异。非 Git 路径会被忽略。

仓库布局

AI Memory/
└── Projects/
    └── <project-slug>/
        ├── Project State.md
        ├── Sessions/
        │   └── YYYY-MM-DD.md
        └── Decisions/
            └── YYYY-MM-DD-<decision-slug>.md

Daily/
└── YYYY-MM-DD.md

AI Memory 文件夹遵循 OBSIDIAN_MEMORY_ROOT。逻辑项目名称会被 slug 化（Spring Authorization Server → spring-authorization-server）。

示例工作流

  1. 在 Cursor 或 VS Code 中打开一个项目。

  2. 在进行实质性工作之前，助手调用 get_project_context。

  3. 在完成有意义的实现之后，它调用 capture_work_session。

  4. 当做出架构选择时，它调用 record_decision。

  5. 当整体状态发生变化时，它调用 update_project_state。

  6. 随时在 Obsidian 中打开仓库以阅读或编辑相同的文件。

安全模型

  • 所有笔记路径必须解析到 OBSIDIAN_VAULT_PATH 内部。

  • 绝对笔记路径、../ 遍历和可检测到的符号链接逃逸都会被拒绝。

  • 在可行的情况下，写入是原子的（tempfile + os.replace）。

  • 这些工具不是通用的文件系统 API。

  • 看起来像秘密的值（密钥、令牌、JWT、私钥、password= 赋值）在写入之前会被替换为 [redacted-secret]。

  • Cursor 规则和 Copilot 指令会告知助手绝不要持久化密码、API 密钥、令牌、JWT、私钥、.env 内容、数据库凭据、生产秘密或敏感的客户数据。

测试

测试使用临时目录，绝不会使用您的真实仓库。

uv run pytest

更广泛的本地检查：

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"
./scripts/smoke-test.sh

冒烟测试验证环境变量、仓库目录、包导入、服务器构造和 pytest 测试套件。

故障排除

症状

需要检查的内容

服务器立即退出

OBSIDIAN_VAULT_PATH 已设置且目录存在

工具未出现在 Cursor 中

项目 .cursor/mcp.json 存在；重新加载窗口；uv 在 PATH 上

工具未出现在 Copilot 中

工作区 .vscode/mcp.json 使用顶层 servers 键，而不是 mcpServers

Path traversal is not allowed

传递仓库相对路径，例如 AI Memory/Projects/spring-auth/Project State.md

决策文件名已存在

服务器写入了 YYYY-MM-DD-<slug>-2.md 而不是覆盖

会话中缺少 Git 部分

repository_path 被省略或不是 Git 仓库；这是非致命的

意外的 stdout 噪音

只有 MCP JSON-RPC 应使用 stdout；日志应放在 stderr 上

许可证

MIT。参见 LICENSE。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Doclea MCP by docleaai

    Doclea MCPofficial

    docleaai
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent memory for AI coding assistants, storing and retrieving architectural decisions, patterns, and solutions across sessions using semantic search, while also offering git integration for commit messages and code expertise mapping.
    MIT

  • LumenCore

    arclightdynamics
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI coding assistants with persistent project memory to retain architectural decisions, code patterns, and domain knowledge across sessions. It stores data locally in a SQLite database, allowing agents to remember, recall, and manage project-specific context using full-text search.
    8
    Apache 2.0

  • mcp-ltm

    kvas-it
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides persistent long-term memory for AI assistants with tag-based retrieval, wiki-style linking, and source references, storing memories as markdown files with SQLite index.
    1
    MIT

  • arcane

    Edition-X
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.
    MIT

View all related MCP servers

Related MCP Connectors

  • NeuroStack

    Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.

  • goldhold

    Persistent memory for AI agents. Search, store, and recall across sessions.

  • Hint-Services-obsidian-github-mcp

    Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmjava/obsidian-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server