obsidian-dev-memory
This MCP server lets AI coding assistants keep persistent project memory as Markdown notes in an Obsidian vault.
Retrieve concise project context from Project State plus recent session and decision notes.
Capture timestamped work-session notes with changes, decisions, next steps, open questions, and optional Git branch/SHA/dirty-state metadata.
Record durable architecture or engineering decisions with context, rationale, alternatives, consequences, and related files.
Update the project’s current state, including objective, architecture, progress, blockers, notes, important files, and next steps.
Search project memory locally by text, with optional project filtering and result limits.
Read a specific Markdown note while enforcing vault-contained path safety.
Append to the daily note, optionally under a unique heading, without overwriting existing text.
Provides persistent engineering memory stored in an Obsidian vault, allowing AI assistants to capture work sessions, record decisions, and read project context from Markdown notes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-dev-memory Capture today's work session and note the decisions we made."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 VaultDeveloper 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+
A local Obsidian vault directory
Git on
PATHonly if you want automatic repository snapshots
Installation
git clone https://github.com/jmjava/obsidian-mcp.git
cd obsidian-mcp
uv syncuv 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_memoryor:
uv run obsidian-dev-memoryThe 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_memoryClaude Desktop setup
Claude Desktop reads a user-level mcpServers file rather than project config:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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/ObsidianVaultOptional:
./scripts/install-project.sh \
--project /home/user/src/example \
--vault /home/user/Documents/ObsidianVault \
--server /path/to/obsidian-dev-memory-mcpIf --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 |
| Read |
| Append a timestamped section to today's session note |
| Write a durable decision note |
| Patch the concise project-state note; omitted fields and unknown H2s stay |
| Scan Project State Next Steps, optional |
| Scan Project State Blocked / Blockers bullets |
| Move a Next Steps, Agent Queue, or TODO item to In Progress; check a matching queue box |
| Move an In Progress, Agent Queue, or TODO item to Completed; check a matching queue box |
| Move a Next Steps or In Progress item to Blocked |
| Move a Blocked or Blockers item back to Next Steps |
| Local filename and text search over project memory and top-level |
| Read one vault-relative Markdown file |
| Append to |
| 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 notesThe AI Memory folder honors OBSIDIAN_MEMORY_ROOT. Logical project names are slugified (Spring Authorization Server → spring-authorization-server).
Example workflow
Open a project in Cursor, VS Code, or Claude Code.
Before substantial work, the assistant calls
get_project_context.After meaningful implementation, it calls
capture_work_session.When an architecture choice is made, it calls
record_decision.When overall status changes, it calls
update_project_state.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 unlabeledscheme://user:pass@hostconnection strings) are replaced with[redacted-secret]before they are written and beforeread_note,get_project_context, andsearch_memoryreturn 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,
.envcontents, 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.shWith 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 |
|
Tools do not appear in Cursor | Project |
Tools do not appear in Copilot | Workspace |
Tools do not appear in Claude Code | Project |
Tools do not appear in Claude Desktop | The user-level |
| Pass vault-relative paths such as |
Decision file name already existed | The server wrote |
Git section missing from a session |
|
Unexpected stdout noise | Only MCP JSON-RPC should use stdout; logs belong on stderr |
License
MIT. See LICENSE.
Available Tools
7 toolsappend_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
Scored across 7 tools
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.
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.
Seven tools is well-scoped for an Obsidian-based development memory server. Each tool covers a distinct need without unnecessary redundancy or bloat.
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
Related MCP Connectors
Persistent engineering memory designed to follow developers across coding agents.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceProvides 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- AlicenseNot gradedqualityDmaintenanceProvides 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 npmApache 2.0
- AlicenseAqualityDmaintenanceEnables 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.6MIT
- AlicenseAqualityCmaintenanceEnables 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.962 npmMIT