Memory & ODIN

HEADING OS does not have "a memory." It has six distinct mechanisms, each tuned to a different shape of recall, plus ODIN — a curated, opinionated long-term brain. All storage resolves under the private data overlay via the data-root seam; the engine never holds real data.

The mental model

Auto-memory is sticky notes that always load; the memory-index is associative recall that finds things by meaning; ODIN is a curated, opinionated long-term brain; the knowledge base is a second brain of atomic notes; threads are live operational state; and dream / memory-hygiene are the maintenance crew.

How they relate. The memory-index (2) is the connective tissue: it indexes across auto-memory, the ODIN brain, threads, CRM, context, reference, plans, knowledge, and deliverable outputs, so /recall answers by meaning over everything. ODIN's own recall mode is a brain-scoped slice of the same engine. Dream (6) consolidates auto-memory (1); memory-hygiene (6) audits both auto-memory and the ODIN brain.

1. Auto-memory — file-based persistent facts

The always-on cross-session memory. Each durable fact is a single Markdown file with YAML frontmatter, and a flat index (MEMORY.md) lists every fact as a one-line pointer. The index is injected into context at the start of every session, so the assistant orients on prior learnings without reading any file body until it needs the detail.

Where it lives: <data-root>/auto-memory/, indexed by auto-memory/MEMORY.md (pointers only, kept under a line budget).

---
name: console-first-no-web-dependency
description: "One-line description — specific enough to judge relevance"
metadata:
  type: feedback        # user | feedback | project | reference
---

The fact, in prose. For feedback/project facts, follow with
**Why:** and **How to apply:** lines.

What NOT to store: code patterns / architecture (derivable by reading the project), git history (authoritative on its own), one-off debugging fixes (the fix is in the code), anything already in a CLAUDE.md, and ephemeral task detail. Memory is for what you cannot re-derive. Fact bodies carry an age banner — memories are point-in-time observations, not live state.

2. Semantic recall / memory-index — associative memory

A local, zero-API-cost associative-memory index (scripts/memory-index.py) that finds notes by meaning — including cross-lingual — where grep finds only exact words. Recall is hybrid: a dense channel (embedding cosine similarity via the local bge-m3 model through Ollama) fused with a sparse channel (SQLite FTS5 BM25) using Reciprocal Rank Fusion, then re-ranked by a weighted blend of relevance, recency, and importance.

It is the "hippocampus": a rebuildable cache, never the source of truth. The notes ("neocortex") stay in git; the index is gitignored.

• Content store: .memory-index/index.db (under the data root) — the private content layers.
• Code store: .memory-index-code/index.db (under the engine root) — a separate store for the code collection (skills, rules), keeping each collection's paths relative to its own side of the seam.

Air-gap is structural: denied paths (the _secure/ prefix and any personal path segment) are never read, so they can never be retrieved — enforced in code, not just config.

Recall in practice (/recall)

uv run python scripts/memory-index.py build                          # refresh (incremental)
uv run python scripts/memory-index.py query "<question>" --json       # default --collection content
#   --collection code   skills/rules     --collection all   both      --layer NAME   pin one layer

The /recall skill reads the top cited files and composes an answer grounded only in what those files say, citing each claim by file path. If the engine reports a gap (nothing above the salience threshold), /recall says so plainly — "not in memory" — and never pads or answers from general knowledge.

Use /recall for workspace-wide recall; /odin recall for brain-scoped only; Grep for exact-string search; /osint for external/world intel (not memory).

3. ODIN brain — the curated long-term advisor

A persistent, opinionated knowledge brain that ingests books, articles, videos, and documents, extracts principles, forms positions, records episodes (things that happened), detects conflicts, and gives referenced first-person advice that prioritizes learned knowledge over general reasoning. Full operating guide below.

Where it lives: <data-root>/knowledge/odin-brain/ — principles/, positions/, episodes/, sources/, conflicts/, and a regenerated INDEX.md with brain stats. Every write is sanitized, then both indexes refresh (brain INDEX.md + the memory-index).

4. Knowledge base / ZK — the second brain

A Zettelkasten second brain over <data-root>/knowledge/: atomic notes, wiki-links, a status lifecycle, and anti-dumping discipline. Driven by /zk with subcommands add | enrich | find | connect | distill | garden | stats | brief. In a single-operator deployment, prefer ODIN / threads / auto-memory; in a multi-user fleet, executives lean on /zk.

5. Threads — operational state as durable memory

An operational registry of ongoing situations, each a dated Markdown file with a ## Log of activity. Managed by /thread (open | log | close | hold | reopen | list | find). The active-thread list is injected into context each session. Lives in <data-root>/threads/business/ (and a personal tree, which is operator-only and excluded from the memory-index by the personal-segment air-gap). Use a thread for a live, multi-step situation with an open/closed lifecycle — not a single fact (auto-memory) or a generic note (/zk).

6. Dream + memory-hygiene — the maintenance crew

They split cleanly: /dream is the fixer (judgement), /memory-hygiene is the detector (mechanical only).

• /dream (explicit-invocation only) — a periodic pass over auto-memory: merges related facts, converts relative dates to absolute, fixes contradictions at the source, deletes superseded files, and keeps MEMORY.md under budget. Runs a mandatory security gate (no secrets ever enter memory) and a docs-validation step, and respects managed-by sections like ## Active Threads.
• /memory-hygiene — runs scripts/memory-hygiene.py across auto-memory + the ODIN brain, flagging only mechanically-verifiable rot (dangling references, orphan files, an over-budget index). It never mutates memory — it hands the worklist to /dream.

Working with ODIN

ODIN is a persistent AI advisor with his own knowledge brain. He forms opinions, defends them, and challenges weak thinking. Every consult answer is referenced (each claim links to its brain origin) and prioritizes learned knowledge over general reasoning.

The principle / position / episode model

ODIN's knowledge is a three-tier ladder plus its raw inputs:

• Source — external material he ingested. The evidence base.
• Principle — one atomic belief, with a confidence (high/medium/low), an ## Application, and ## Boundaries. Extracted from sources or taught directly.
• Position — a committed stance synthesized from multiple principles, with a revisit_when condition and ## Known Weaknesses.
• Episode — dated lived evidence of something that happened. It has no confidence (it is a happening, not a conviction), sits below principles and positions, and never overrides them; it only becomes a belief by maturing into a principle through reflect, with explicit human confirmation.

Conflicts are a fifth file type recording a direct contradiction for the human to resolve — ODIN never resolves a conflict silently. The ladder: episodes graduate into principles; principles cluster into positions. Notes are never deleted when superseded — temporal-validity fields mark history instead.

The 9 modes

Invoke as /odin [mode] [source-or-question]. With no arguments, ODIN shows a mode menu.

ODIN's non-negotiable rules

1. Knowledge priority is sacred — brain knowledge always comes before general reasoning.
2. Challenge is mandatory on every consult — no exceptions.
3. Never resolve conflicts silently — report and wait for human direction.
4. Source everything; first person always ("I think", not "based on analysis").
5. Honest about gaps — if the brain is empty, say so and offer to learn.
6. All writes stay inside knowledge/odin-brain/, are sanitized, and refresh both indexes.
7. The collect air-gap runs in code first — the personal/secure boundary is enforced before any text reaches the model, never delegated to it.