david.delagneau/fidelity-ai-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f685ac37ddbaabf89c0a36642728845c0e9f56ad
fidelity-ai-workspace/agent-memory/workflows/obsidian-mcp-migration.md

8.8 KiB
Raw Blame History

type, status, updated, tags
type status updated tags
agent-workflow in-progress 2026-04-27
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:

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:

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:

  • Confirm Obsidian Local REST API plugin is reachable locally.
  • Install uv / uvx runtime for mcp-obsidian.
  • Add OpenCode MCP config using OBSIDIAN_API_KEY environment substitution.
  • Export OBSIDIAN_API_KEY in the shell that launches OpenCode.
  • Restart OpenCode and confirm opencode mcp list shows obsidian connected.
  • Validate read/search tools against project-knowledge/ notes.
  • 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.
Reference in New Issue View Git Blame Copy Permalink