# OMN — the memory system in this folder

One idea: **facts are the truth, the card is the window, close-out is one command.**
The agent's native episodic memory (Mnemopi) is the fuzzy recall layer; these files
are the precise truth layer. Canon wins on conflict.

## The 3 rules

1. **Facts are the only prose.** Edit `facts/`, `decisions/`, `watch.md`,
   `learnings.md`, `projects/`, `backlog.md`, `inbox.md`. Never duplicate their
   content anywhere else — README is pointers, card.md is generated.
2. **The card is the window.** `card.md` is rendered by `tools/build.sh` from
   frontmatter — never hand-edit it. If a fact is past its `check:` interval, the
   card shows `⚠STALE`.
3. **Close-out is one command.** `tools/close.sh` — engine health (optional) →
   check.sh → doctor.sh gates → drain inbox → rebuild card → briefing → git
   snapshot. Zero drift possible.

## Rituals

- **Open:** read `core/card.md` → pull a fact file or skill only if the task needs it.
- **Look-up protocol:** card → topic match → open the fact/decision →
  `tools/recall.sh` <keyword> or grep core/ → ask the human. Don't guess.
- **Capture (mid-session):** change the owning fact / append a decision / append a
  learning line. `check.sh` is the freshness gate; close-out regenerates the card.
- **Close:** `tools/close.sh` (~60s; needs git for the snapshot step).
- **Clean mode:** memory never auto-loads — reading the card IS the explicit ask.

## Layout

```
core/
├── card.md        # generated — the whole open ritual
├── README.md      # this file — pointers only
├── facts/         # verified truth, SSoT — 4 files, ≤60 lines each
│   ├── protocols.md   # the numbered operating rules (live from first boot)
│   ├── hardware.md    # CANDIDATE — verify your machine, then promote to live
│   ├── engines.md     # CANDIDATE — the serving matrix, fill from reality
│   ├── frontier.md    # CANDIDATE — parking lot for candidates under the adoption bar
├── decisions/     # ADRs 0000+ — proposed → accepted → superseded
├── watch.md       # candidates & gates, one table
├── learnings.md   # append-only SUCCESS log, newest first
├── sessions/      # one daily briefing file per day
├── projects/      # active only; done → archive/
├── backlog.md     # open questions + pending work
├── inbox.md       # one file; drained by close.sh
├── sky/           # the memory sky — the canon drawn as a night sky (tools/sky.sh)
├── archive/       # tombstoned + history — move, never delete
└── tools/
    ├── build.sh   # facts → card.md (no deps)
    ├── check.sh   # schema + staleness + dead links — the "live" gate
    ├── doctor.sh  # reality drift: dead paths, dead providers, role pins, served ids
    ├── health.sh  # served-model pulse (optional engine gate)
    ├── close.sh   # the whole close-out ritual + git auto-commit
    ├── recall.sh  # exact grep; Mnemopi is the fuzzy layer
    ├── graph.sh   # canon link-graph → graph.json (wiki-link + supersedes edges)
    └── sky.sh     # regrow the memory sky (sky.template.html → sky/)
```

Add a fact domain by adding a file under facts/ with proper frontmatter — the card
picks it up on the next build. Start a feed/analyzer in a core/ subdirectory only when
a real need appears; reference it from this README so `doctor.sh` can guard it.

## Status model

- Facts: `live` (verified truth) → `superseded`/`archived` (tombstoned to archive/)
  · `candidate` (to be verified — never treat as truth)
- Decisions: `proposed` → `accepted` → `superseded`
- Projects: `active` · `done` · `parked`

## Conventions

- Frontmatter on every fact/decision/project: `title, status, updated, priority,
  check (facts only, e.g. 7d), summary (one line for the card), tags, related`.
- Cross-refs — wiki-links in double brackets — `check.sh` verifies they resolve.
- Learnings are append-only lines, newest first.
- Retirement = move to `archive/`, never delete (trash-principle, facts/protocols.md).