Obsidian Developer Memory MCP

Ein lokaler Model Context Protocol-Server, der KI-Coding-Assistenten wie Cursor und GitHub Copilot ein dauerhaftes Entwicklungsgedächtnis verleiht.

Das Gedächtnis wird in gewöhnlichen Markdown-Dateien in einem Obsidian-Vault gespeichert. Obsidian muss dafür nicht laufen. Es gibt weder ein Community-Plugin noch einen Obsidian-API-Schlüssel.

Derselbe stdio-MCP-Server funktioniert sowohl mit Cursor als auch mit GitHub Copilot / VS Code.

Architektur

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

Warum direktes Markdown?«, "Warum direktes Markdown?"

Der Vault ist die Quelle der Wahrheit. Notizen bleiben in Obsidian, in Git oder in einem beliebigen Texteditor lesbar und bearbeitbar. Der Server ist niemals davon abhängig, dass Obsidian geöffnet ist, kommuniziert nie mit einer gehosteten Speicher-API und schreibt nie in eine proprietäre Datenbank.

Voraussetzungen

• Python 3.12+

• uv

• Ein lokales Obsidian-Vault-Verzeichnis

• Git im PATH nur, wenn du automatische Repository-Snapshots möchtest

Installation

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

uv sync installiert das offizielle Python-SDK und das Projektpaket.

Konfiguration

Erforderlich:

export OBSIDIAN_VAULT_PATH="$HOME/Documents/ObsidianVault"

Optional:

export OBSIDIAN_MEMORY_ROOT="AI Memory"

OBSIDIAN_MEMORY_ROOT ist standardmäßig auf AI Memory gesetzt. Die MCP-Konfiguration des Editors kann diese Variablen direkt bereitstellen. Dieses Projekt enthält .env.example zu Dokumentationszwecken; der Server lädt .env-Dateien nicht automatisch.

Starten des Servers

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

uv run python -m obsidian_dev_memory

oder:

uv run obsidian-dev-memory

Der Prozess kommuniziert per MCP über stdio. Schreibe keine Anwendungsprotokolle nach stdout; Diagnosen gehören nach stderr.

Einrichtung für Cursor

Die Cursor-Konfiguration auf Projektebene liegt in .cursor/mcp.json und verwendet das aktuelle mcpServers-Format. Eine übertragbare Vorlage liegt 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"
      }
    }
  }
}

Dieses Repository enthält außerdem .cursor/rules/obsidian-memory.mdc, das Cursor mittgeübermittelt, wann Lese- und Schreibzugriffe auf den Vault erfolgen sollen.

Maschinenspezifische .cursor/mcp.json-Dateien werden vom Installer erzeugt und hier nicht eingecheckt.

Einrichtung für GitHub Copilot / VS Code

Die Workspace-Konfiguration für Copilot / VS Code liegt in .vscode/mcp.json und verwendet das aktuelle servers-Format. Eine übertragbare Vorlage liegt 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 gibt Copilot dasselbe Speicherverhalten wie Cursor.

Verwendung des Installers

Binde diesen Server in ein anderes Entwicklungsprojekt ein:

./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

Wenn --server nicht angegeben wird, leitet das Skript dieses Repository anhand seines eigenen Speicherorts ab.

Der Installer erstellt oder aktualisiert:

• <project>/.cursor/mcp.json

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

• <project>/.vscode/mcp.json

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

Er bricht mit einer klaren Fehlermeldung ab, wenn das Zielprojekt oder der Vault fehlt, und führt MCP-JSON zusammen, sodass nicht verwandte Server nicht zerstört werden.

MCP-Tools

get_project_context liefert bei einem neuen Projekt leere Abschnitte, statt einen Fehler zu erzeugen.

record_decision schreibt YYYY-MM-DD-<decision-slug>.md. Wenn diese Datei bereits existiert, fügt der Server anstelle eines Überschreibens ein numerisches Suffix an (-2, -3, ...).

capture_work_session akzeptiert eine optionale repository_path. Wenn dieser Pfad auf ein Git-Repository verweist, erfasst die Notiz Repository-Namen, Branch, kurzen SHA, Dirty-Status sowie eine kurze Liste geänderter Dateien. Vollständige Diffs werden niemals geschrieben. Ein Nicht-Git-Pfad wird ignoriert.

Vault-Struktur

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

Der Ordner AI Memory richtet sich nach OBSIDIAN_MEMORY_ROOT. Logische Projektnamen werden slugifiziert (Spring Authorization Server → spring-authorization-server).

Beispiel-Workflow

1. Öffne ein Projekt in Cursor oder VS Code.

2. Vor größerer Arbeit ruft der Assistent get_project_context auf.

3. Nach aussagekräftiger Implementierung ruft er capture_work_session auf.

4. Eine nachhaltige Architekturentscheidung ruft er mit record_decision.

5. Bei Änderungen am Gesamtstatus ruft er update_project_state auf.

6. Öffne den Vault in Obsidian, um dieselben Dateien zu bearbeiten.

Sicherheitsmodell

• Alle Notizpfade müssen innerhalb von OBSIDIAN_VAULT_PATH aufgelöst werden.

• Absolute Notizpfade, ../-Traversierung und erkennbare Symlink-Ausbrüche werden abgelehnt.

• Schreibvorgänge sind, wo möglich, atomar (tempfile + os.replace).

• Die Tools sind keine allgemeine Dateisystem-API.

• Werte, die wie Geheimnisse aussehen (Schlüssel, Token, JWTs, private Schlüssel, password=-Zuweisungen), werden **durch [redacted-secret] ersetzt, bevor sie geschrieben werden.

• Es gibt keine (z. B. Passwörter, API-Schlüssel, Token, JWTs, private Schlüssel, .env`-Inhalte, Datenbank-Zugangsdaten, Produktionsgeheimnisse oder sensible Kundendaten) dürfen vom Assistenten dauerhaft gespeichert werden. Dies verlangen Cursor-Regeln und Copilot-Anweisungen.

Tests

Tests verwenden temporäre Verzeichnisse, niemals dein echtes Vault.

uv run pytest

Eine umfassendere lokale Prüfung:

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

Der Smoke-Test prüft die Umgebungsvariable, das Vault-Verzeichnis, den Paketimport, den Serveraufbau sowie die pytest-Suite.

Fehlerbehebung

Lizenz

MIT. Siehe LICENSE.