GitGudBrain Public Handbook (INT-341)#

1. Introduction & The Cognitive Substrate#

GitGudBrain is the underlying cognitive memory substrate and reverse-reflection engine powering the Sophia/Nomos ecosystem. While nomos acts as the deterministic, mathematical enforcer of the physical codebase (Law 1), GitGudBrain represents the evolving semantic wisdom of the Intent Plane.

It enables AI Agents to maintain conversational continuity, distill massive conversational trajectories into high-density vector embeddings, and seamlessly recall architectural constraints (Knowledge Items) across thousands of independent execution waves without human intervention.

2. The Self-Learning Feedback Loop (Autonomous Resolution)#

GitGudBrain solves the "human-in-the-loop friction" problem by transitioning the ecosystem from manual recovery to an autonomous Closed-Loop Control System.

Instead of a human manually fixing SQLITE_BUSY locks or DoD verification failures, GitGudBrain orchestrates auto-resolution:

1. Friction Detection (Telemetry): The sophia-soma daemon monitors all nomos task sync executions. If the Substrate throws a DoD Gate Failure (e.g., Cognitive Debt Score Violation, AST Anti-Shim Violation), the stack trace and context are intercepted.
2. Dynamic Task Minting: The daemon automatically executes nomos task create --type Debt "Auto-Resolve Gate Failure: [Task-ID]" and dumps the failure logs into the Intent markdown file.
3. Subagent Invocation: A headless Tier-2 Agent is spawned in the background. It reads the failure, queries GitGudBrain for similar past resolutions, modifies the AST, and forces the sync until it passes.
4. Distillation: The human only sees the final merged result.

3. Core Mechanisms & Vector Architecture#

3.1 The Vector Store Topology#

GitGudBrain relies on a deeply integrated, localized vector database (SQLite + sqlite-vec or local ChromaDB) residing in the agent's application data directory (<appDataDir>/knowledge/).

• Zero External Dependencies: Ensuring the Hermetic Worktree Law extends to memory, all vectors are stored locally.
• Embedding Model: Fast, high-dimensional local embedding models (or cached cloud models) transform raw markdown SSoTs and historical chat trajectories into queryable mathematical spaces.

3.2 The Distillation Pipeline (The LEARN Phase)#

Raw conversation transcripts (transcript.jsonl) are too massive and noisy to store directly. During the LEARN phase (post-sync):

1. Trajectory Parsing: GitGudBrain strips tool-call boilerplates and extracts only the decisions, failures, and architectural pivots.
2. KI (Knowledge Item) Generation: It generates highly condensed summaries (metadata.json).
3. Vectorization: These KI summaries, alongside the final Go AST structures, are embedded and written to the database.

3.3 Reverse-Reflection & Context Rehydration#

When an agent begins a new task via nomos task start, they do not start with a blank slate.

• Semantic Querying: The task's Intent Motivation is vectorized and used to query GitGudBrain for the Top-K nearest neighbors.
• System Prompt Injection: The most relevant KIs, past bug resolutions, and architectural rules are dynamically injected into the Agent's <knowledge_items> context block before the agent writes a single line of code.
• Result: The agent instantly knows the historical context of the repository.

4. Semantic Hygiene & Entropy Decay#

Just as the Substrate requires deterministic compilation, the Intent Plane requires Semantic Hygiene.

GitGudBrain continuously runs background sweeps (via sophia-soma) to measure Cluster Entropy:

• Superseded Memories: If an ADR (Architectural Decision Record) is marked as SUPERSEDED, GitGudBrain automatically decays the weights of its associated vectors.
• Cognitive Debt Detection: If an agent frequently queries a specific cluster of KIs but repeatedly fails the nomos verify gates, the database flags that module as possessing high "Cognitive Debt", forcing a refactor.

5. Next Generation (Gen3) Subsumption#

As the ecosystem matures, GitGudBrain transitions from a passive database to the primary steering mechanism of the Sovereign Swarm. While Nomos handles the rigid 2PC commits and CapBAC locks, GitGudBrain autonomously dictates what tasks should be worked on next by analyzing the vector space for gaps in the architectural coverage.

// @intent INT-341