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

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.
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.
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 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).