Obsidian Developer Memory MCP

Локальный сервер Model Context Protocol, который даёт ИИ-ассистентам для кодирования, таким как Cursor и GitHub Copilot, постоянную инженерную память.

Память хранится в виде обычных Markdown-файлов в хранилище Obsidian. Obsidian не должен быть запущен. Нет ни плагина сообщества, ни API-ключа Obsidian.

Тот же 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

• Git в PATH, только если нужны автоматические снимки репозитория

Установка

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

Процесс общается по MCP через stdio. Не пишите журналы приложения в 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 возвращает пустые разделы, когда проект новый, вместо ошибки.

record_decision записывает YYYY-MM-DD-<decision-slug>.md. Если такой файл уже существует, сервер добавляет числовой суффикс (-2, -3, ...) вместо перезаписи.

capture_work_session принимает необязательный repository_path. Когда этот путь является Git-репозиторием, заметка записывает имя репозитория, ветку, короткий SHA, состояние dirty и краткий список изменённых файлов. Полные диффы никогда не записываются. Путь, не являющийся 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.

Устранение неполадок

Лицензия

MIT. См. LICENSE.