Skip to main content
Glama
obsidian-dev-memory
by jmjava

Obsidian Developer Memory MCP

A local Model Context Protocol server that gives AI coding assistants such as Cursor, GitHub Copilot, and Claude persistent engineering memory.

Memory is stored as ordinary Markdown files in an Obsidian vault. Obsidian does not need to be running. There is no community plugin and no Obsidian API key.

The same stdio MCP server works with Cursor, GitHub Copilot / VS Code, Claude Code, and Claude Desktop.

Architecture

Cursor Agent --------------------\
                                  \
GitHub Copilot / VS Code -------- > MCP stdio server
                                  /        |
Claude Code / Claude Desktop ----/         v
                               obsidian-dev-memory
                                        |
                                        v
                               Obsidian Markdown Vault
Developer opens spring-auth in Cursor, VS Code, or Claude Code
        |
        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

Why direct Markdown?

The vault is the source of truth. Notes remain readable and editable in Obsidian, git, or any text editor. The server never depends on Obsidian being open, never talks to a hosted memory API, and never writes a proprietary database.

Requirements

  • Python 3.12+

  • uv

  • A local Obsidian vault directory

  • Git on PATH only if you want automatic repository snapshots

Installation

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

uv sync installs the official MCP Python SDK and the project package.

Configuration

Required:

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"

Optional:

export OBSIDIAN_MEMORY_ROOT="AI Memory"

OBSIDIAN_MEMORY_ROOT defaults to AI Memory. Editor MCP configuration can supply these variables directly. This project includes .env.example for documentation; the server does not automatically load .env files.

Running the server

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

uv run python -m obsidian_dev_memory

or:

uv run obsidian-dev-memory

The process speaks MCP over stdio. Do not write application logs to stdout; diagnostics go to stderr.

Cursor setup

Project-level Cursor config lives at .cursor/mcp.json and uses the current mcpServers format. A portable template is in 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"
      }
    }
  }
}

This repository also ships .cursor/rules/obsidian-memory.mdc, which tells Cursor when to read and write memory.

Machine-specific .cursor/mcp.json files are created by the installer and are not committed here.

GitHub Copilot / VS Code setup

Workspace Copilot / VS Code config lives at .vscode/mcp.json and uses the current servers format. A portable template is in 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 gives Copilot the same memory behavior as Cursor.

Claude Code setup

Project-level Claude Code config lives at .mcp.json and uses the same mcpServers format as Cursor. A portable template is in config/claude.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"
      }
    }
  }
}

.claude/rules/obsidian-memory.md gives Claude Code the same memory behavior as Cursor and Copilot. The installer writes that rule file instead of overwriting an existing CLAUDE.md.

Machine-specific .mcp.json files are created by the installer and are not committed here. Claude Code may ask you to approve the project server on first use.

Alternatively, add the server from Claude Code:

claude mcp add --scope project --transport stdio \
  --env OBSIDIAN_VAULT_PATH=/ABSOLUTE/PATH/TO/OBSIDIAN/VAULT \
  obsidian-dev-memory -- \
  uv --directory /ABSOLUTE/PATH/TO/obsidian-dev-memory-mcp \
  run python -m obsidian_dev_memory

Claude Desktop setup

Claude Desktop reads a user-level mcpServers file rather than project config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Merge the same server entry from config/claude.mcp.json.example into that file, then restart Claude Desktop.

Installer usage

Wire this server into another development project:

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

Optional:

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

If --server is omitted, the script infers this repository from its own location.

The installer creates or updates:

  • <project>/.cursor/mcp.json

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

  • <project>/.vscode/mcp.json

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

  • <project>/.mcp.json

  • <project>/.claude/rules/obsidian-memory.md

It fails clearly when the target project or vault is missing, and it merges MCP JSON so unrelated servers are not destroyed.

MCP tools

Tool

Purpose

get_project_context

Read Project State.md plus the newest session and decision notes

capture_work_session

Append a timestamped section to today's session note

record_decision

Write a durable decision note

update_project_state

Patch the concise project-state note; omitted fields and unknown H2s stay

list_open_tasks

Scan Project State Next Steps, optional Agent Queue.md checkboxes, and open TODO/*.md notes

list_blocked_tasks

Scan Project State Blocked / Blockers bullets

claim_task

Move a Next Steps, Agent Queue, or TODO item to In Progress; check a matching queue box

complete_task

Move an In Progress, Agent Queue, or TODO item to Completed; check a matching queue box

block_task

Move a Next Steps or In Progress item to Blocked

unblock_task

Move a Blocked or Blockers item back to Next Steps

search_memory

Local filename and text search over project memory and top-level TODO/*.md. Daily notes are included only when no project filter is set

read_note

Read one vault-relative Markdown file

append_daily_note

Append to Daily/YYYY-MM-DD.md; same-title headings must be unique

quality_pool_flow

Return the quality-pool contract: cap 7, selection order, and the workflow gate

get_project_context returns empty sections when a project is new instead of failing.

record_decision writes YYYY-MM-DD-<decision-slug>.md. If that file already exists, the server adds a numeric suffix (-2, -3, ...) instead of overwriting.

capture_work_session accepts an optional repository_path. When that path is a Git repository, the note records repository name, branch, short SHA, dirty state, and a short changed-file list. Full diffs are never written. A non-Git path is ignored.

update_project_state patches Project State.md: omitted fields keep existing sections, an empty list clears that list section, and unknown H2 headings survive. list_open_tasks returns Next Steps bullets, unchecked - [ ] lines from AI Memory/Agent Queue.md when that note exists, and open top-level TODO/*.md notes (frontmatter status: open and/or unchecked items). It does not create Agent Queue.md. list_blocked_tasks returns Blocked and Blockers bullets from Project State and does not write vault files. claim_task / complete_task parse the current Project State, move one matching Next Steps or In Progress bullet (or a unique Agent Queue or TODO item when Project State has no match), and rewrite the note through update_project_state so other sections are preserved. A match must be unique across Project State, Agent Queue, and TODO after stripping trailing #tags / [repo::...]; docs is ambiguous when it hits both Write docs and a different queue line. When a unique unchecked Agent Queue checkbox is the same canonical task as the matched item, that line is checked in place before Project State is rewritten (the raw query is not reused); other queue lines stay put. A missing Agent Queue is reported as unchecked and is never created. An ambiguous match fails without moving the Project State bullet, so a claim cannot succeed while leaving matching boxes open. A unique matching TODO note is marked in_progress or done; a unique matching TODO checkbox is checked in place. block_task moves one matching Next Steps or In Progress bullet to Blocked through the same rewrite path and does not check Agent Queue boxes or rewrite TODO notes. unblock_task moves one matching Blocked or Blockers bullet back to Next Steps the same way and also leaves Agent Queue boxes and TODO notes alone. They do not write daily notes. Match by exact text or a unique substring of one canonical task. Secret-looking values in listed or moved bullets are replaced with [redacted-secret].

append_daily_note splices under a heading only when that title is unique in the daily note. heading="Usage" will not write under a burn-plan Usage at the top when a later Usage exists. Concurrent appends take an exclusive lock outside the vault so they are not last-write-wins. The lock file is not written into the vault.

search_memory indexes AI Memory/Projects/** plus top-level TODO/*.md. Daily/*.md is included only when no project filter is set. A search for a TODO title finds that note. Nested TODO/finished/ is not scanned. The tool does not invent Agent Queue.md.

Vault layout

AI Memory/
├── Agent Queue.md          # optional shared checkbox list; claim/complete may check a match
└── Projects/
    └── <project-slug>/
        ├── Project State.md
        ├── Sessions/
        │   └── YYYY-MM-DD.md
        └── Decisions/
            └── YYYY-MM-DD-<decision-slug>.md

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

TODO/
└── YYYY-MM-DD-<slug>.md   # real backlog; list/claim/complete/search scan top-level notes

The AI Memory folder honors OBSIDIAN_MEMORY_ROOT. Logical project names are slugified (Spring Authorization Server → spring-authorization-server).

Example workflow

  1. Open a project in Cursor, VS Code, or Claude Code.

  2. Before substantial work, the assistant calls get_project_context.

  3. After meaningful implementation, it calls capture_work_session.

  4. When an architecture choice is made, it calls record_decision.

  5. When overall status changes, it calls update_project_state.

  6. Open the vault in Obsidian at any time to read or edit the same files.

Security model

  • All note paths must resolve inside OBSIDIAN_VAULT_PATH.

  • Absolute note paths, ../ traversal, and detectable symlink escapes are rejected.

  • Writes are atomic (tempfile + os.replace) where practical.

  • The tools are not a general filesystem API.

  • Secret-looking values (keys, tokens, JWTs, private keys, password= assignments, and unlabeled scheme://user:pass@host connection strings) are replaced with [redacted-secret] before they are written and before read_note, get_project_context, and search_memory return text. Reads do not rewrite vault files.

  • Cursor rules, Copilot instructions, and Claude Code rules tell the assistant never to persist passwords, API keys, tokens, JWTs, private keys, .env contents, database credentials, production secrets, or sensitive customer data.

Testing

Tests use temporary directories, never your real vault.

uv run pytest
uv run ruff check src/ tests/

Pull requests run pytest, ruff, and scripts/smoke-test.sh in .github/workflows/pytest.yml. A second push to the same ref cancels the older run. A redact, wipe, claim, or foreign-server merge regression fails CI.

The smoke job creates a temporary fixture directory and sets OBSIDIAN_VAULT_PATH to that path. It does not use a home vault. A path that is set but is not a directory fails the job.

A broader local check:

./scripts/smoke-test.sh

With OBSIDIAN_VAULT_PATH unset, the smoke test uses a temporary directory and deletes it afterward. A path that is set but missing, such as /tmp/missing, fails and is not created. The script checks that create_server still registers the MCP tools, then runs pytest. Set SMOKE_SKIP_PYTEST=1 to stop after the tool check.

Troubleshooting

Symptom

What to check

Server exits immediately

OBSIDIAN_VAULT_PATH is set and the directory exists

Tools do not appear in Cursor

Project .cursor/mcp.json is present; reload the window; uv is on PATH

Tools do not appear in Copilot

Workspace .vscode/mcp.json uses a top-level servers key, not mcpServers

Tools do not appear in Claude Code

Project .mcp.json uses a top-level mcpServers key; approve the server if prompted; uv is on PATH

Tools do not appear in Claude Desktop

The user-level claude_desktop_config.json includes the mcpServers entry; restart Claude Desktop

Path traversal is not allowed

Pass vault-relative paths such as AI Memory/Projects/spring-auth/Project State.md

Decision file name already existed

The server wrote YYYY-MM-DD-<slug>-2.md instead of overwriting

Git section missing from a session

repository_path was omitted or is not a Git repository; that is non-fatal

Unexpected stdout noise

Only MCP JSON-RPC should use stdout; logs belong on stderr

License

MIT. See LICENSE.

Available Tools

7 tools
append_daily_noteB

Append an item to Daily/YYYY-MM-DD.md without overwriting existing text.

Inputs: content (required), date, heading. Returns: object

capture_work_sessionA

Capture meaningful work performed during a coding session.

Appends a timestamped section to that day's session note. When repository_path is a Git repo, records branch, short SHA, and dirty state. Never persist secrets or full diffs.

Inputs: project (required), summary (required), changes, decisions, +3 more. Returns: object

get_project_contextA

Retrieve concise durable memory before substantial work.

Reads Project State.md plus the newest session and decision notes. Returns empty sections when the project is new. Never returns the entire vault.

Inputs: project (required), recent_sessions, recent_decisions. Returns: object

read_noteA

Read one Markdown note inside the configured Obsidian vault.

The path must stay inside OBSIDIAN_VAULT_PATH. Absolute paths and traversal such as ../ are rejected.

Inputs: path (required). Returns: object

record_decisionA

Store a durable architecture or engineering decision.

Creates YYYY-MM-DD-.md. If that file already exists, a numeric suffix is added instead of overwriting.

Inputs: title (required), context (required), project (required), decision (required), +4 more. Returns: object

search_memoryB

Search project state, sessions, and decisions with local text matching.

Inputs: query (required), limit, project. Returns: result

update_project_stateA

Replace the concise durable Project State.md for a project.

This is current state, not a session log. Omit empty sections.

Inputs: project (required), notes, blocked, completed, +6 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct memory artifact or action: context retrieval, session capture, decision recording, state updating, searching, reading, and appending to daily notes. Even though several tools involve notes, their purposes are clearly separated.

    Naming Consistency5/5

    All tool names follow a consistent lowercase snake_case verb_noun pattern such as capture_work_session, record_decision, and append_daily_note. The naming is predictable and makes the tool's purpose immediately clear.

    Tool Count5/5

    Seven tools is well-scoped for an Obsidian-based development memory server. Each tool covers a distinct need without unnecessary redundancy or bloat.

    Completeness4/5

    The toolkit covers core memory workflows: reading context, capturing sessions, recording decisions, updating state, searching, and appending daily notes. Minor gaps exist around deleting or listing notes, but these are not essential for the stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      Not graded
      quality
      D
      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.
      3 npm
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to store and retrieve project context, bugs, decisions, and session logs by reading and appending markdown files in a local Obsidian vault, without requiring any cloud services.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables coding agents to use an Obsidian vault as long-term memory, with search, reading, and writing of notes, plus automatic capture of learnings that are propagated to MOCs, daily notes, and the knowledge index with git commits.
      9
      62 npm
      MIT