Obsidian Developer Memory MCP

Cursor 및 GitHub Copilot과 같은 AI 코딩 어시스턴트에 영구적인 엔지니어링 메모리를 제공하는 로컬 Model Context Protocol 서버입니다.

메모리는 Obsidian 볼트에 일반 Markdown 파일로 저장됩니다. 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에 메모리를 읽고 써야 하는 시기를 알려주는 .cursor/rules/obsidian-memory.mdc도 포함되어 있습니다.

머신별 .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, 더티 상태 및 변경된 파일 목록을 기록합니다. 전체 diff는 절대 기록되지 않습니다. 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를 따릅니다. 논리적 프로젝트 이름은 슬러그화됩니다(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를 참조하십시오.