fidelity-ai-workspace/core/integrations/memory-vault-model.md

Project Knowledge Memory 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 project-knowledge/.

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

Memory Interface

Use scripts/memory/memory.sh for project-knowledge operations:

• root prints the configured memory root
• read <path> reads a project-knowledge-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_PROJECT_KNOWLEDGE_DIR: canonical project knowledge directory. Defaults to <workspace-root>/project-knowledge.
• AIW_MEMORY_VAULT_DIR: transition alias for the canonical project knowledge directory.
• AIW_MEMORY_BACKEND: auto, files, or obsidian. Defaults to auto.
• AIW_OBSIDIAN_VAULT_DIR: Obsidian-specific transition alias, 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 -> project-knowledge/06-daily/
• work-item -> project-knowledge/02-work-items/
• person -> project-knowledge/04-people/
• decision -> project-knowledge/05-decisions/
• system -> project-knowledge/03-context/systems/
• workstream -> project-knowledge/03-context/workstreams/
• meeting-note -> project-knowledge/06-daily/

Templates live in project-knowledge/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 project knowledge health checks.
• Prefer Obsidian CLI property operations for frontmatter/property edits when available, especially on existing notes that appear in Bases, because the CLI reduces YAML formatting drift.
• 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 project-knowledge/; 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 Obsidian/project knowledge health checks.

These are optional enhancements. The canonical memory remains Markdown.