Memory Vault Integration Model

Purpose

Define a project-agnostic interface for reading, creating, searching, and validating the canonical Markdown memory.

Obsidian is the current human-facing implementation, but the workspace should not depend on Obsidian-specific behavior for core memory maintenance.

Layers

Canonical Memory

The source of truth is plain Markdown under vault/.

Agents should edit canonical notes directly when precision matters because direct edits produce auditable diffs.

Memory Interface

Use scripts/memory/memory.sh for vault-level operations:

root prints the configured memory root
read <path> reads a vault-relative note
search <query> [folder] searches memory
create <type> <slug> [title] creates a note in the canonical folder from the matching template
base-query <base-name> [format] queries a structured view when supported
health checks required files and optional navigation health

Tool Adapter

The current adapter is Obsidian CLI through scripts/obsidian/cli.sh.

If Obsidian CLI is unavailable or fails, scripts/memory/memory.sh falls back to direct Markdown operations unless AIW_MEMORY_BACKEND=obsidian is explicitly set.

Configuration

AIW_MEMORY_VAULT_DIR: canonical memory directory. Defaults to <workspace-root>/vault.
AIW_MEMORY_BACKEND: auto, files, or obsidian. Defaults to auto.
AIW_OBSIDIAN_VAULT_DIR: Obsidian-specific vault override, still supported by the adapter.
AIW_OBSIDIAN_VAULT_NAME: Obsidian URI vault name override for URI wrappers.

Backend meanings:

auto: use Obsidian CLI when useful and available; otherwise use direct Markdown.
files: force direct Markdown behavior.
obsidian: require Obsidian CLI for supported operations and fail if unavailable.

Note Type Routing

The memory interface owns type-to-folder routing:

daily -> vault/06-daily/
work-item -> vault/02-work-items/
person -> vault/04-people/
decision -> vault/05-decisions/
system -> vault/03-context/systems/
workstream -> vault/03-context/workstreams/
meeting-note -> vault/06-daily/

Templates live in vault/09-templates/.

This gives agents an automatic destination for new notes without coupling the rule to Obsidian.

Agent Rules

Use the memory interface when creating new canonical notes from a known type.
Use the memory interface for broad search, Base queries, and vault health checks.
Edit Markdown directly for precise memory curation, corrections, and content updates.
Do not treat Obsidian CLI failure as project context.
Do not require Obsidian to be running for core workspace operation.
Keep raw evidence outside vault/; promote only curated memory.

Useful Obsidian CLI Operations

When available, Obsidian CLI improves human-facing memory workflows:

search:context gives Obsidian-aware search context.
create path=... template=... creates notes from templates.
base:query reads Bases as structured views.
properties and property:* inspect or update metadata.
unresolved, orphans, links, backlinks, and tags support vault health checks.

These are optional enhancements. The canonical memory remains Markdown.

3.2 KiB Raw Blame History