# 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 `workspaces/<profile>/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` uses direct Markdown operations unless `AIW_MEMORY_BACKEND=obsidian` is explicitly set.

---

## Configuration

- `AIW_PROJECT_PROFILE`: selected profile. Defaults to `fidelity` in this workspace.
- `profiles/<profile>/workspace.json`: canonical source for `knowledge_dir`, `inbox_dir`, and `index_dir`.
- `AIW_PROJECT_KNOWLEDGE_DIR`: optional local override for the canonical project knowledge directory.
- `AIW_MEMORY_BACKEND`: `auto`, `files`, or `obsidian`. Defaults to `auto`.
- `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` -> `workspaces/<profile>/project-knowledge/06-daily/`
- `work-item` -> `workspaces/<profile>/project-knowledge/02-work-items/`
- `person` -> `workspaces/<profile>/project-knowledge/04-people/`
- `decision` -> `workspaces/<profile>/project-knowledge/05-decisions/`
- `system` -> `workspaces/<profile>/project-knowledge/03-context/systems/`
- `workstream` -> `workspaces/<profile>/project-knowledge/03-context/workstreams/`
- `meeting-note` -> `workspaces/<profile>/project-knowledge/06-daily/`

Templates live in `workspaces/<profile>/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 `workspaces/<profile>/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.