feat: integrate Obsidian MCP server via opencode config and add migration strategy documentation

2026-04-27 09:54:27 -06:00
parent e19a10f588
commit de7f2b02f6
3 changed files with 289 additions and 1 deletions
--- a/agent-memory/maps/tooling.md
+++ b/agent-memory/maps/tooling.md
@@ -1,7 +1,7 @@
 ---
 type: agent-map
 domain: tooling
-updated: 2026-04-17
+updated: 2026-04-27
 tags:
  - map
  - tooling
@@ -61,5 +61,6 @@ Commands, prompts, skills, workflows, and automation surfaces that make the work

 - Project-agnostic memory scripts: `scripts/memory/`
 - Current Obsidian adapter: `scripts/obsidian/`
+- Obsidian MCP migration plan: `agent-memory/workflows/obsidian-mcp-migration.md`
 - Project knowledge vault: `project-knowledge/`
 - Agent operating memory: `agent-memory/`
--- a/agent-memory/workflows/obsidian-mcp-migration.md
+++ b/agent-memory/workflows/obsidian-mcp-migration.md
@@ -0,0 +1,274 @@
+---
+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.