--- type: agent-workflow status: in-progress updated: 2026-04-27 tags: [obsidian, mcp, migration, memory] --- # Obsidian MCP Migration Plan ## Goal Replace the current Obsidian CLI-backed adapter path with an Obsidian MCP-first integration while preserving the workspace memory model: - `project-knowledge/` remains the canonical source of truth - `scripts/memory/` remains the stable workspace memory contract - direct Markdown edits remain the safe fallback for precise curation - Obsidian stays an adapter/navigation layer, not a second memory store --- ## Current State Current access path: ```text agent -> scripts/memory/memory.sh -> scripts/obsidian/cli.sh -> obsidian CLI -> vault ``` Current Obsidian-specific helper scripts: - `scripts/obsidian/cli.sh` - `scripts/obsidian/open.sh` - `scripts/obsidian/search.sh` - `scripts/obsidian/daily.sh` - `scripts/obsidian/uri.sh` Current memory-interface features that rely on Obsidian CLI when available: - note creation from templates - search with context - Base queries - selected health/navigation checks Phase 1 integration status as of 2026-04-27: - OpenCode project config now declares a local MCP server named `obsidian`. - The configured command is `/opt/homebrew/bin/uvx mcp-obsidian`. - The Obsidian Local REST API endpoint is reachable at `https://127.0.0.1:27124/` and reports plugin version `3.6.1` with Obsidian `1.12.7`. - The server currently depends on the caller providing `OBSIDIAN_API_KEY` through the shell environment; do not commit this secret. --- ## Target State Preferred access path: ```text agent -> memory interface rules -> Obsidian MCP -> vault ``` The migration should change the adapter, not the memory model. --- ## Non-Goals - Do not move canonical memory out of Markdown - Do not encode promotion rules into the MCP layer - Do not make `project-knowledge/` depend on Obsidian-only storage - Do not remove direct Markdown editing as a fallback - Do not delete the current scripts until MCP coverage is validated in real use --- ## Capability Mapping ### Move to Obsidian MCP - vault search - search with context - Base queries - backlinks / links / orphans / unresolved checks - property read/write operations - template-based note creation if supported cleanly by the MCP ### Keep as workspace logic - note type routing (`work-item`, `person`, `decision`, etc.) - memory promotion rules - evidence vs canonical-memory separation - workspace-specific health expectations - fallback to direct Markdown operations - metadata expectations for work items, daily notes, people, decisions, and context notes --- ## Phased Rollout ## Phase 1 - Validate MCP Coverage Confirm the selected Obsidian MCP supports the operations the workspace already depends on. Required coverage: - read file contents - create note from path and optionally template - search vault - query Bases or equivalent structured views - read and write frontmatter/properties - list backlinks/links or equivalent relationship data Current Phase 1 checklist: - [x] Confirm Obsidian Local REST API plugin is reachable locally. - [x] Install `uv` / `uvx` runtime for `mcp-obsidian`. - [x] Add OpenCode MCP config using `OBSIDIAN_API_KEY` environment substitution. - [x] Export `OBSIDIAN_API_KEY` in the shell that launches OpenCode. - [x] Restart OpenCode and confirm `opencode mcp list` shows `obsidian` connected. - [x] Validate read/search tools against `project-knowledge/` notes. - [x] Validate write/append/delete behavior on a disposable test note before touching canonical memory. - [ ] Determine whether Bases/properties/backlinks/template behavior needs to remain on the existing CLI/direct-Markdown path. Phase 1 validation results: - `list_files_in_vault` works and returns the expected top-level project-knowledge folders. - `list_files_in_dir` works for folders such as `01-current`. - `get_file_contents` works for canonical notes such as `01-current/current-work.md`. - `simple_search` works and returns scored/contextual matches across the vault. - `append_content` can create and append to a disposable note. - `delete_file` can delete a disposable note. - `patch_content` with `target_type=heading` failed against a disposable note with `invalid-target`; treat heading-targeted patching as not yet validated. Decision rule: - If MCP cannot cover create/search/properties/Base-query well enough, keep the current CLI path as a partial adapter instead of forcing a full replacement. --- ## Phase 2 - Switch Documentation To MCP-First Update behavior and architecture docs so they describe: - Obsidian MCP as the preferred adapter when available - `scripts/memory/` as the stable workspace contract - direct Markdown editing as the safe fallback - the CLI path as legacy or transitional Primary files to update: - `AGENTS.md` - `.opencode/agents/fidelity.md` - `.opencode/agents/workspace.md` - `README.md` - `profiles/fidelity/profile.md` - `core/README.md` - `core/integrations/memory-vault-model.md` - `core/integrations/obsidian-model.md` - `agent-memory/integrations/memory-interface.md` - `agent-memory/integrations/obsidian.md` - `agent-memory/memory/context-maintenance.md` - `agent-memory/workflows/workspace-architecture.md` - `scripts/memory/README.md` - `.opencode/commands/memory-create.md` - `.opencode/commands/memory-health.md` --- ## Phase 3 - Deprecate Obsidian CLI Helpers Mark these as deprecated in comments/docs before removal: - `scripts/obsidian/cli.sh` - `scripts/obsidian/open.sh` - `scripts/obsidian/search.sh` - `scripts/obsidian/daily.sh` - `scripts/obsidian/uri.sh` Notes: - human convenience wrappers may be kept longer than agent-facing wrappers - `scripts/memory/` should not be deleted just because the adapter changes --- ## Phase 4 - Remove Unused Adapter Scripts Delete only after: - MCP has been used successfully in normal workflows - no agent instructions still reference the old scripts - command docs no longer direct users to the old CLI path - there is no remaining human workflow dependency worth preserving Likely delete first: - `scripts/obsidian/cli.sh` - `scripts/obsidian/uri.sh` Delete later only if truly unused: - `scripts/obsidian/open.sh` - `scripts/obsidian/search.sh` - `scripts/obsidian/daily.sh` --- ## Cleanup Matrix ### Keep - `project-knowledge/.obsidian/` - `project-knowledge/08-bases/*.base` - `project-knowledge/09-templates/` - `scripts/memory/` ### Deprecate then remove - `scripts/obsidian/*` agent-facing wrappers that become redundant under MCP ### Update in place - commands that call `bash scripts/memory/memory.sh ...` - docs that explicitly say "Obsidian CLI" is the preferred adapter - rules that recommend CLI property edits --- ## Risks - over-coupling the workspace to a specific MCP implementation - deleting the stable memory contract too early - partial migration that leaves conflicting instructions in docs - assuming MCP supports templates/Bases/properties exactly like the CLI --- ## Rollback Strategy If MCP integration is incomplete or unstable: - keep `scripts/memory/` as the default contract - keep CLI helpers until capability parity exists - continue direct Markdown edits for precise curation - treat MCP as additive until it proves reliable in real workflows --- ## Immediate Next Steps 1. Choose the exact Obsidian MCP implementation and document its supported operations. 2. Build a capability parity checklist against the current CLI-backed flow. 3. Update the workspace docs to MCP-first wording without deleting the CLI path yet. 4. Add deprecation notes to `scripts/obsidian/*` once the new path is active. 5. Remove old scripts only after references and real usage are gone. --- ## Initial Candidate - `MarkusPfundstein/mcp-obsidian` - GitHub: `https://github.com/MarkusPfundstein/mcp-obsidian` - Integration model: MCP server that talks to Obsidian through the Obsidian Local REST API community plugin. - Documented tools include file listing, file reads, search, content patching, append, and delete. - Requires validating whether it covers this workspace's Base-query, property/frontmatter, backlinks, and template workflows well enough to replace the current CLI adapter. ## Candidate Rejected Or Not Recommended - `jacksteamdev/obsidian-mcp-tools` - GitHub: `https://github.com/jacksteamdev/obsidian-mcp-tools` - Features documented by the project include vault access, semantic search, and template integration. - Dependencies include Obsidian Local REST API, and optional/recommended plugins such as Templater and Smart Connections. - The repository currently carries a prominent "Project Unmaintained" security notice from the maintainer. - The maintainer specifically recommends migrating to a plugin that implements MCP over HTTP/SSE rather than relying on a downloaded local executable model. - Do not use this as the primary migration target for this workspace unless no safer maintained option is available and the risk is explicitly accepted.