Backend: `obsidian`

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Routes a subsystem's persistence into an Obsidian vault. AIWG writes Markdown files directly into the vault's filesystem; Obsidian's file watcher picks up changes within a few seconds.

When to use

• You already use Obsidian as your personal knowledge system and want AIWG memory / kb / reflections in your graph.
• You want full-text search and graph view over AIWG artifacts via Obsidian's native UI.

Configuration

{
  "version": "1",
  "backends": {
    "memory": {
      "type": "obsidian",
      "vault": "~/vaults/main",     // required: absolute or ~/-prefixed path
      "folder": "AIWG/memory",      // optional: subfolder within the vault
      "useCli": true                // optional, default true
    }
  }
}

Field	Required	Notes
`vault`	yes	Absolute path to the vault directory; `~/` expanded
`folder`	no	Subfolder inside the vault. Default: vault root. Use to scope AIWG writes
`useCli`	no	Default `true`. When true, probes `obsidian the version option` once on init

No env vars required.

How it works

The adapter does direct filesystem reads/writes against `<vault>/<folder>/`. It does not touch Obsidian's `.obsidian/` config directory — for read, write, delete, AND list (skipped during walk).

When `useCli: true` (the default), `init()` runs `obsidian the version option` once and emits a one-time stderr warning if the binary is missing. This is informational only — direct filesystem writes still work without the CLI installed. Obsidian's own file watcher converges on external markdown changes within seconds.

Frontmatter handling

`WriteMeta.frontmatter` (passed by AIWG skills via `aiwg <subsystem> put`) is rendered as YAML frontmatter at the top of the markdown:

---
tags: [ai, note]
created: 2026-04-28
---
body content here

If the content already starts with a `---` YAML block, the existing frontmatter is preserved and `WriteMeta.frontmatter` is ignored — never overwritten.

YAML scalars with special characters (colons, hashes, quotes) are auto-quoted. Arrays render inline (`[a, b, c]`).

Capabilities

Operation	Notes
`read`	Returns `null` for missing files; refuses paths into `.obsidian/`
`write`	Auto-creates parent directories; merges frontmatter when content has none
`list`	Recursive walk; `.obsidian/` is skipped
`delete`	No-op for missing; refuses `.obsidian/`
`query`	Not implemented — Obsidian search isn't exposed via the official CLI yet

Path safety

Same five rules as the `fs` adapter (`..`/absolute/`~`/backslash/empty), plus the explicit `.obsidian/` refusal. Tested in `test/unit/storage/obsidian.test.ts`.

Caveats

• Obsidian's index lags by a few seconds when AIWG writes externally. If a user has Obsidian open and you write a file via AIWG, expect 1–3 seconds before the file appears in the file tree / graph view.
• Obsidian Sync conflicts: if Obsidian Sync (or another sync plugin) is also writing to the same vault, external writes can race with sync. The recommended workflow is to either pause Sync during heavy AIWG ingest, or scope AIWG to a `folder` that Sync ignores.
• The CLI integration is conservative: `useCli: true` only probes the CLI's existence. AIWG does not synthesize CLI commands to drive the running app — the official CLI's command surface for arbitrary write workflows isn't fully verified yet. Future versions may invoke `obsidian` to trigger reload-after-write.
• `query` is not implemented: full-text search through AIWG isn't possible on this backend. Use Obsidian's native search UI on the resulting files.

Setup

1. Install Obsidian and create a vault (or pick an existing vault). 2. (Optional) Install the official Obsidian CLI: see https://help.obsidian.md/cli 3. Add the backend to `.aiwg/storage.config`:

   {
     "version": "1",
     "backends": {
       "memory": {
         "type": "obsidian",
         "vault": "~/vaults/main",
         "folder": "AIWG/memory"
       }
     }
   }

4. Verify connectivity:

Use AIWG to complete this documented outcome: 4. Verify connectivity
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

5. (Optional) Migrate existing AIWG memory into the vault:

Use AIWG to complete this documented outcome: 5. (Optional) Migrate existing AIWG memory into the vault
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

See `docs/storage/migration.md` for details.

See also

• `docs/storage/security.md` — credential handling, path safety
• `docs/storage/migration.md` — moving existing data into the vault
• Obsidian help: https://help.obsidian.md