GAIA Brain -- Knowledge Layer

The GAIA Brain is a read-only knowledge layer that turns a project's own artifacts -- stories, epics, requirements, architecture decisions, tests, reviews, and UX designs -- into a queryable governance graph. It answers the question "for this story, what governs it, what tests it, and what designs sit alongside it?" in a single call, without leaving the terminal.

Overview

The Brain lives at .gaia/knowledge/ as an Obsidian-native Markdown vault. It consists of two files:

  • brain-index.yaml -- the single source of truth (SSOT) manifest. Every indexed artifact has one entry here, carrying its path, a content hash, a short synopsis, tags, and typed governance edges.
  • brain-index.md -- a human-readable Map of Content (MOC) rendered from the manifest. Browse it in Obsidian or any Markdown viewer to navigate the knowledge layer. It is a derived convenience -- the YAML manifest is the authority.

The Brain does not copy artifact bytes. Each index entry points at the artifact's canonical path in place. When you query the Brain, it walks the manifest's typed edges and surfaces the relevant nodes; when you want the full content, it gives you the path to read it yourself.

The knowledge model

Each entry in the manifest represents one artifact and carries:

  • Path -- the canonical location of the artifact on disk.
  • Content hash -- a sha256 digest of the file at index time, used for freshness checks.
  • Synopsis -- a deterministic one-line summary (first heading plus first prose line), generated at index time.
  • Tags -- artifact-type tags harvested from frontmatter and directory structure.
  • Edges -- typed governance relationships to other nodes, described below.

Edge types

The Brain recognizes a closed set of seven edge types. Every edge in the manifest is one of these, and no other edge type is invented at index time.

Edge type Direction Meaning
implements UP This artifact implements a requirement.
governed-by UP This artifact is governed by an architecture decision.
decomposes UP This artifact is a child of a larger artifact (story decomposes an epic).
verified-by DOWN This artifact is verified by a test.
reviewed-in DOWN This artifact was reviewed in a review report.
traces-to UP This artifact traces to a governance target declared in its frontmatter.
designs LATERAL This artifact is a design companion (UX, wireframe) for the node.

The governance envelope

When you query the Brain for a story, the result is its governance envelope -- every related artifact grouped into three directions:

  • UP -- the governance chain above the story: the requirements it implements, the architecture decisions that govern it, and its parent epic. The walk is bounded and transitive -- it follows the story up through its epic to the requirements and decisions, with a depth cap and a cycle guard so the walk always terminates.
  • DOWN -- the artifacts below the story: tests that verify it and reviews that gated it. A single hop from the seed.
  • LATERAL -- the design artifacts that sit alongside the story: UX specs, wireframes. A single hop from the seed.

The envelope gives you the full governance picture of a story without opening a single file by hand.

The linked predicate

The Brain's health view classifies every indexed artifact as linked or unlinked using a four-source predicate. A node is linked if any of the following resolves:

  1. The artifact's frontmatter contains a non-empty traces_to field.
  2. The artifact's frontmatter contains an epic field.
  3. An allocation row in the epics registry references this artifact.
  4. A mapping in the traceability matrix includes this artifact.

An artifact that satisfies none of the four is unlinked.

Unlinked is a signal, not a failure

An unlinked node is a passive quality signal. It is never treated as an error, and it is normal and expected that many artifacts appear unlinked. The linked predicate is meaningful for story-shaped nodes -- the artifacts that should trace to a requirement, an epic, or a test. Non-story artifacts such as meeting notes, action items, brainstorm outputs, retrospectives, READMEs, and architecture-decision shards legitimately have no governance edges. Their presence in the unlinked list is expected, not a problem to fix.

On a mature project with thousands of indexed artifacts, it is typical for the majority of entries to carry no edges -- because the bulk of the artifact tree is non-story material. This is healthy. Use the unlinked list to spot story artifacts that should have traceability but do not, and ignore the rest.

Content integrity (C1)

Every synopsis in the manifest carries the source file's content hash at the time of indexing. When a downstream consumer -- such as the query command -- surfaces a synopsis, it recomputes the hash of the canonical file on disk and compares. If the file has changed since the last reindex, or is missing, the node is marked stale and the consumer falls through to the canonical file path so you read the current bytes directly. A stale synopsis is never served as if it were current.

This means the Brain is always safe to query, even when the index is out of date -- stale entries are surfaced transparently, and a reindex clears them.

When the index is built

The index is built by /gaia-brain-reindex. There are two modes of invocation:

  • Automatic at sprint-close. /gaia-sprint-close runs a best-effort, non-blocking reindex as part of its finalize step. If the reindex fails, the sprint still closes -- the failure is logged as a warning. This means that on a project with a healthy sprint cadence, the index stays reasonably current without any manual effort.
  • On-demand. Run /gaia-brain-reindex at any time to force a mid-sprint refresh. Common reasons: you want to bootstrap the index on an existing or brownfield project before the first sprint-close, or you made a burst of artifact edits and want the index to reflect them immediately.

A fresh greenfield project does not need to run the reindex early -- the first sprint-close populates the index automatically.

Reindex is idempotent and incremental: a second run short-circuits unchanged files via the content hash, making re-runs fast.

Read-only boundary

The Brain is a strict read-only consumer of the artifacts it indexes. It never modifies an artifact, never copies artifact bytes into the knowledge store, and never writes outside .gaia/knowledge/.

The Brain is also separate from the validator's ground-truth sidecar (the per-agent working memory at .gaia/memory/). The reindex sweep does not read or write the memory tree; the ground-truth refresh does not read or write the knowledge index. They are independent subsystems serving different purposes -- the Brain indexes governance relationships, while the ground-truth sidecar tracks filesystem-level facts for artifact validation.

No vectors, no embeddings

The entire knowledge layer is built on grep, tags, and the manifest. There is no vector database, no embedding model, and no external search service anywhere in this stack. Retrieval works by walking the typed edges in the manifest and matching tags. This keeps the Brain zero-dependency, deterministic, and auditable -- every edge in a query result can be traced back to a concrete declaration in a frontmatter field, an epics registry row, or a traceability matrix mapping.

Commands

Six commands expose the Brain to users and agents:

Command Purpose
/gaia-brain-reindex Rebuild the index from source. The sole writer of the manifest. Runs automatically at sprint-close and on demand.
/gaia-brain-query Query a story's governance envelope (UP / DOWN / LATERAL). Read-only. Users and agents invoke it explicitly -- automatic consultation is planned but not yet shipped.
/gaia-brain-health List every artifact the linked predicate classifies as unlinked. A passive quality signal -- unlinked non-story artifacts (meeting notes, retros, etc.) are normal.
/gaia-feed Ingest an external document (URL, local file, or stdin) into the knowledge store with provenance frontmatter and register it in the brain index. One-gesture ingestion -- slug and tags are auto-inferred.
/gaia-knowledge-refresh Re-fetch ingested sources and replace only what changed. Hash-gated three-way reconcile: skip on match, overwrite on diff, mark failed and preserve stale file on fetch error. Runs an expiry sweep afterward.
/gaia-unfeed Remove an ingested document from the knowledge store. Deletes the ingested file and de-registers the brain-index entry atomically. The inverse of /gaia-feed.

Ingested-document lifecycle

The three ingestion commands form a complete lifecycle for external documents in the knowledge layer:

  1. Ingest -- /gaia-feed brings a document into the store with provenance tracking and a configurable TTL (default 30 days).
  2. Refresh -- /gaia-knowledge-refresh re-fetches all ingested sources, updating changed content and marking unreachable sources as failed. Entries whose TTL has elapsed without revalidation transition to stale.
  3. Remove -- /gaia-unfeed deletes an ingested document and its index entry when the source is no longer needed.

How do I update or remove an ingested source?

  • Update: Re-run /gaia-feed with the same --slug. The existing ingested file and brain-index entry are overwritten atomically with fresh content and provenance. No need to remove first.
  • Remove: Run /gaia-unfeed <slug>. The ingested file is deleted and the index entry is de-registered. Idempotent -- a no-op if the slug is not present.