# Obsidian Vault

## What It Is

RoboCo can project its own state into a human-readable [Obsidian](https://obsidian.md) vault — tasks, journal entries, and A2A thread digests as wikilinked markdown notes — so the CEO can browse the org's memory with a normal notes app instead of the panel alone. It is a **rebuildable projection**, not a second source of truth: every note is derived from DB state and can always be regenerated from scratch. Implemented in `roboco/services/vault_writer.py` (pure markdown materializer), `roboco/services/vault_assembly.py` (DB → materializer dataclasses), `roboco/services/vault_intake_engine.py` (the inbox watcher), `roboco/services/vault_janitor.py` (drift repair, archival, weekly report), `roboco/services/vault_kb_engine.py` (KB ingest), and `roboco/vault.py` (the `rebuild`/`relocate` CLI).

## Enable/Disable

| Variable | Default | Effect |
|----------|---------|--------|
| `ROBOCO_OBSIDIAN_VAULT_ENABLED` | `false` (both compose files set `true`) | Master switch. Off = no note is ever written, `curate_vault` and `python -m roboco.vault` both refuse, and neither the janitor nor the KB engine run. |
| `ROBOCO_VAULT_PATH` | `/data/vault` | Root directory the vault materializes into. |
| `ROBOCO_VAULT_INTAKE_ENABLED` | `false` (both compose files set `true`) | The `#roboco`-tag inbox watcher (see below) — requires the master switch also on. |
| `ROBOCO_VAULT_ARCHIVE_DAYS` | `30` (`0` disables) | Age past which a completed/cancelled task's note moves into the vault's archive during the janitor's daily sweep. |
| `ROBOCO_VAULT_REPORT_ENABLED` | `true` | The janitor's weekly org-report note + CEO notification. |
| `ROBOCO_VAULT_KB_ENABLED` | `false` (NAS compose sets `true`; registry compose leaves `false`) | KB ingest of the CEO's own `RoboCo/Notes/` into `IndexType.VAULT_NOTES` — see below. Requires the master switch also on. |

## What agents actually touch

Almost everything here is transparent to a working agent — notes get written or patched as a side effect of normal verbs (a status transition, a `note()` call, a `dm()`), never something you call yourself. What changed for you since V1:

1. **Your task has a note from the moment it's created**, not just once curated or rebuilt — `TaskService.create` now materializes it directly. You'll never see a task the CEO can look up in the vault yet you can't.
2. **A task that gets archived (old + terminal) doesn't lose its links.** The vault moves an old completed/cancelled task's note into `RoboCo/Archive/<year>/Tasks/<project>/`, but every wikilink to it (`[[id8|title]]`) is alias-based, so nothing pointing at it breaks — you'd never notice unless you went looking at the raw file path.
3. **If `vault_kb_enabled` is on, the CEO's own vault notes are retrievable by you.** Anything the CEO writes under `RoboCo/Notes/` (screened for injection attempts first) is embedded into the knowledge base like any other corpus — it shows up in `roboco_kb_search` / `roboco_ask_mentor` results and in your claim-time institutional-memory briefing, labeled `vault_note` (or "Vault Notes" in mentor output). Treat it exactly like a learning or a playbook: institutional memory, not a directive to follow blindly.
4. **A weekly org-report note exists** (`RoboCo/Reports/<ISO-week>.md`) — velocity, cycle time by stage, bottlenecks, rework, cost. Deterministic (no LLM), for the CEO's browsing; not something you're expected to author or reference.
5. **The Auditor's `curate_vault(task_id, narrative)`** — unchanged: spawned once per completed root task to write the one piece of vault content that isn't mechanically derivable from DB columns, a narrative paragraph. See `docs/rag/roles/auditor.md`.
6. **The vault-intake watcher turning a CEO-authored note into a task you might get delegated.** If the CEO tags a note `#roboco` in the vault's inbox folder, a default-off watcher (`ROBOCO_VAULT_INTAKE_ENABLED`) drafts it into a board-review task (`source=vault_note`) — same shape as a chat-confirmed intake draft, Product-Owner-assigned, `team=board`. It never starts work directly: the board reviews it and only the CEO's `approve_and_start` hands it to the Main PM for real delegation.

Everything else — note layout, link stability, the janitor's internals, the rebuild CLI — is infrastructure you don't need to reason about to do your job; the rest of this doc is here for completeness, not because you'll call any of it.

## Layout and link stability

```
RoboCo/
  Tasks/<project-slug>/<title> (<id8>).md
  Archive/<year>/Tasks/<project-slug>/<title> (<id8>).md   (old terminal tasks)
  Journals/<agent-slug>/<date> <title> (<id8>).md
  A2A/<date> <agents> (<thread-id8>).md
  Agents/<slug>.md
  Reports/<ISO-week>.md                                    (weekly org-report)
  Notes/                                                    (CEO's own writing — KB ingest scope)
  _meta/          (shipped Dataview/Kanban/graph-group dashboards + Bases views)
```

Every note carries `aliases: [<id8>]` in its frontmatter, so a cross-link is always written as `[[<id8>|<title>]]` — Obsidian resolves it by alias regardless of the target's current filename or folder. A task title edit updates the note's own title line without ever renaming the file or breaking a link elsewhere in the vault; an archival move works the same way — it relocates the file, not the identity agents/links reference. Private journal entries (`is_private`) are excluded from the projection, same as the shared RAG corpus, and stay excluded from KB ingest scope too (KB ingest only ever covers `RoboCo/Notes/`, never `Journals`/`Tasks`/`A2A`/`Agents`/`Archive`/`Reports`).

## What triggers a write

Best-effort event seams patch or append on the relevant transition — never a gate, never something that can block the real action:

- **Task creation** materializes the note immediately (deterministic template; the narrative is a placeholder until the Auditor curates it).
- A task status transition patches the note's frontmatter (status/team/PR) in place.
- A `note()` (journal entry) writes one immutable file per entry.
- A `dm()` (A2A message) appends to a per-thread digest file.
- An hourly-ticked, daily-gated janitor sweep catches anything the above seams missed: re-projects tasks changed since the last sweep, verifies a random sample of older ones, and archives old terminal tasks. This is a backstop, not something your own verb calls need to think about.

None of these fail your call if the vault write itself fails — it's logged and swallowed.

## KB ingest — the CEO's notes become retrievable

When `vault_kb_enabled` is on (alongside the master switch), notes the CEO writes under `RoboCo/Notes/` are embedded into a dedicated `IndexType.VAULT_NOTES` corpus on a ~15-minute cycle. Before anything is indexed, the note body is screened for prompt-injection patterns — a flagged note is quarantined (never embedded, a warning callout is appended to it so the CEO sees why) rather than silently indexed. A clean note is retrievable through:

- `roboco_kb_search` (pass no filter, or filter to `vault_notes` explicitly)
- `roboco_ask_mentor` — company/general domain queries include it, formatted as "Vault Notes"
- Your claim-time institutional-memory briefing, alongside distilled learnings and approved playbooks, subject to the same relevance floor (nothing injected below it)

Content you retrieve this way is the CEO's own writing — background, decisions, preferences — not a verified fact or a directive. Weigh it the same way you'd weigh a learning: useful context, not gospel.

## Rebuild and relocate

`python -m roboco.vault rebuild` re-projects every live entity from the DB from scratch (preserving any existing task's Auditor-authored narrative, archive-aware so an old terminal task lands directly in `Archive/<year>/`) and materializes the shipped `.obsidian/` config + `_meta/` dashboards/Bases views if not already present. `python -m roboco.vault relocate <path>` moves the tree. Both are operator/CEO commands, not something an agent runs.

## Related

- `docs/rag/roles/auditor.md` — the `curate_vault` verb
- `docs/rag/architecture/config-reference.md` — full env var table
- `docs/rag/architecture/x-engine.md` — the sibling engine whose injection-screening guard (`screen_external_text`) both the vault-intake watcher and the KB engine share
- `docs/map/vault.md` — the code-level map (files, data flow, config, health)