---
type: guide
project: fidelity
status: active
updated: 2026-04-16
tags: [onboarding, obsidian, workspace]
related:
  - start-here.md
  - ../07-maps/ai-workspace-core.md
---

# Workspace Architecture

This repository has two layers:

- `vault/` is the clean Obsidian second brain and canonical AI memory.
- Everything outside `vault/` is technical runtime, reusable core, profile configuration, scripts, commands, prompts, or raw evidence.

---

## Canonical Memory

Use these folders as the source of truth for humans and AI agents:

- `00-start/` for onboarding and usage guidance
- `01-current/` for current work state
- `02-work-items/` for ticket/task memory
- `03-context/` for systems, workstreams, process, and iOS context
- `04-people/` for people and role memory
- `05-decisions/` for confirmed decisions
- `06-daily/` for daily notes
- `07-maps/` for graph hubs
- `08-bases/` for table-style review
- `09-templates/` for note templates

---

## Runtime Outside The Vault

These folders are intentionally outside Obsidian memory:

- `.opencode/` stores agents and slash commands.
- `core/` stores reusable workspace logic.
- `profiles/` stores project-specific profile declarations.
- `scripts/` stores connectors, importers, and wrappers.
- `ai/inbox/` stores live evidence from communication sync.
- `scripts/*/generated/` stores extracted evidence.

Runtime and generated files can be used as evidence, but durable project facts should be promoted into `vault/`.

---

## Memory Access Layer

Use `scripts/memory/` as the platform-agnostic interface to canonical memory.

Obsidian is the current visual and CLI-backed adapter, but the source of truth remains Markdown under `vault/`.

- Agents use `scripts/memory/memory.sh create` when a new typed note is needed.
- Agents use `scripts/memory/memory.sh search` or direct Markdown reads for context lookup.
- Agents use `scripts/memory/memory.sh base-query` and `health` for structured review.
- Precise memory edits should still be made directly to Markdown so changes stay auditable.

---

## Memory Rule

Promoted memory lives in `vault/`.

Raw inbox and generated connector evidence stays outside the vault until the agent promotes durable facts.