GAIOS Memory System

1 · Canon — the deterministic layer

Dense ≤8 KB markdown reference cards (/opt/gaios/canon/*.md, Gitea branch main), one per fact/domain/incident — the single source of truth for anything deterministic (ports, IPs, paths, rules, incidents). — cards today. Edited only via canon_set (commit + push); searchable in Recall within ~60 s. The forcing function: pull the card and cite it inline before stating an infra fact.

2 · Recall — the similarity layer (live)

ChromaDB on 127.0.0.1:8000, four collections, all embedded by nomic-embed-text (768-dim) served VPS-local at 127.0.0.1:11434 (one embedder for index and query). Queried via the recall MCP tool — embed → search each collection → merge, sort L2 ascending.

Distance scale (probe-derived): ≤300 good · 300–400 loose · >400 noise (a random query scores ~443).

3 · The Indexer — polling, near-real-time

gaios_indexer.py (gaios-indexer.service) polls every 60 s: hash-change → re-embed + upsert; deleted → remove; failure → log + skip. Live: — documents tracked, status —. Every durable write becomes searchable within ~60 s automatically.

4 · The Spine — required, not similar anti-amnesia

Vector recall returns what is similar, never what is required. The Project Spine closes that gap: a curated, machine-verified, per-project dependency-validity DAG (/home/ubuntu/api/spines/<project>.json, engine spine.py). A node = a validity-critical obligation whose absence invalidates downstream output; status is computed by running the node's typed checks — no passing verifier, never "done". Hint-scoped (semantic, bind threshold 0.6); >1 match → MULTIPLE SPINES MATCHED — confirm rather than guess. Live: — spines (—) with — open gaps.

5 · Spine-first recall — the RECALL↔SPINE coupling 2026-06-06

Recall is the workhorse (hundreds/day) and used to be spine-blind. Now recall starts from the spine — and the two are coupled through a single embedding:

Conservative by design — false authority (a wrong spine injected as "required") is worse than a missing one, so binding needs a margin and never silently picks on a tie. Single-embed; cached profile embeddings + TTL gaps cache → warm cost is a few cosines. Fail-safe: if the spine engine is down, recall still returns its hits. Per-token auto-recall stays spine-blind by design (spine injection at machine speed would bloat and stall). Engine: /home/ubuntu/api/recall_spine.py.

6 · Auto-recall & get_context — always-on

• Per-turn auto-recall — every minister LLM turn through inference_proxy is hard-injected with a <gaios_recall_context> block (embed user text → top-K → prepend) before the model sees the prompt.
• get_context — the session bootstrap. Given the opening message as a hint it assembles (now spine-first): SPINE gaps, recall hits, identity profile, active projects, pending tasks, recent sessions/ideas. One call and the agent is grounded.

7 · Write paths & consumers

8 · Service & file index

9 · Agent access — wiring the brain into an agent HESTIA pattern

A local agent (e.g. HESTIA, qwen3.5:9b on the GPU via relay) does not get the brain by default — its built-in memory_search hits only its own near-empty local store. The GAIOS brain is wired in through a three-tier bridge, designed so a small model reliably chooses to use it.

The lesson that drove this design: the first build wired GAIOS recall as an exec+curl recipe in the agent’s soul. The model ignored it, called its native (empty) memory_search, and concluded “nothing found.” The fix was to make memory a native, well-named, well-described tool and to verify behaviourally — ask the live model to “dig the memory and list unfinished projects” and confirm it calls gaios_recall_context and names real projects. Full step-by-step in canon: skill-create-local-agent-with-gaios-memory-2026-06-06.