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