Cluster Knowledge and Context

Cluster Knowledge and Context

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/axis/main_test.go
• docs/lifecycle.md
• internal/api/main_test.go
• internal/git/doc.go
• internal/git/git.go
• internal/git/git_test.go
• internal/knowledge/context.go
• internal/knowledge/context_test.go
• internal/knowledge/execution.go

The internal/knowledge package serves as the aggregation layer for AXIS, transforming raw cluster data into a structured, queryable context. It synthesizes information from the Snapshot Plane (real-time node facts), the Persistence Plane (cluster state and historical observations), and the local environment (Git workspace) into a unified payload used by AI agents, safety evaluators, and the execution engine internal/knowledge/context.go:1-11.

ClusterKnowledge Architecture

The primary data structure is ClusterKnowledge, which acts as a point-in-time manifest of the cluster's cognitive and physical state internal/knowledge/context.go:13-21.

Data Aggregation Pipeline

The Build function orchestrates the assembly of this context by performing the following operations:

1. Snapshot Cloning: Creates a deep copy of the current ClusterSnapshot to prevent mutation of the global state internal/knowledge/context.go:26-29.
2. Reservation Overlay: Invokes snapshotview.ApplyReservationView to subtract pending resource commitments (RAM/VRAM) from the free totals, ensuring agents see "allocatable" memory rather than just "free" memory internal/knowledge/context.go:30.
3. Service Mapping: Flattens node-specific metadata, such as OllamaInfo, into a top-level map for quick lookup by service name internal/knowledge/context.go:32-37.
4. Local Workspace Context: Queries the local filesystem for Git repository state (branch, commit hash, and dirty file status) internal/knowledge/context.go:39-43.
5. Telemetry Normalization: Extracts 1-minute load averages from node resources into a simplified Load map internal/knowledge/context.go:55-59.

Code Entity Space: Context Assembly

This diagram illustrates how disparate code entities are merged into the ClusterKnowledge struct.

graph TD
    subgraph "Fact and State Sources"
        A["models.ClusterSnapshot"]
        B["state.ClusterState"]
        C["git.GetRepoState()"]
    end

    subgraph "internal/knowledge"
        D["knowledge.Build()"]
        E["knowledge.ClusterKnowledge"]
    end

    subgraph "Logic Helpers"
        F["snapshotview.ApplyReservationView()"]
    end

    A --> D
    B --> D
    C --> D
    D --> F
    F --> D
    D --> E
    
    E -->|JSON()| G["Agent/Safety Context"]

Loading

Sources: internal/knowledge/context.go:25-61, internal/knowledge/context.go:63-66

Execution Context

For tasks being prepared for execution, the system generates an ExecutionContextJSON. This payload extends the standard cluster knowledge with task-specific metadata required for safety gating and script injection internal/knowledge/execution.go:10-20.

Payload Schema

The execution context includes several top-level keys used by the script registry and external agents:

Key	Description	Source
timestamp	UTC time of context generation	k.Timestamp
best_node	The node selected by the placement engine	decision.Node
snapshot	The reservation-aware cluster snapshot	k.Snapshot
state	Historical failure records and skills	k.State
decision	Full placement reasoning and scores	models.PlacementDecision
task_desc	The natural language intent of the task	taskDesc
git	Local repository status (if applicable)	k.Git

Sources: internal/knowledge/execution.go:21-41

Git Integration

The knowledge system integrates local workspace awareness via the internal/git package. This allows the cluster to be "repository-aware"—for example, refusing to run a deployment task if the local repository has uncommitted changes internal/git/git.go:13-24.

The GetRepoState function captures:

• Identity: Current branch and HEAD commit hash internal/git/git.go:57-65.
• Dirty Status: A count of modified files and a list of the first 10 modified file paths internal/git/git.go:71-92.
• Sync Status: How many commits the local branch is ahead or behind its upstream tracking branch internal/git/git.go:94-103.

Natural Language to Code Entity Mapping

This diagram shows how environmental concepts (like a "dirty git repo") are translated into code entities consumed by the ClusterKnowledge system.

graph LR
    subgraph "Natural Language Space"
        NL1["'Are there uncommitted changes?'"]
        NL2["'Which branch am I on?'"]
        NL3["'Is the cluster overloaded?'"]
    end

    subgraph "Code Entity Space"
        CE1["git.RepoState.IsDirty"]
        CE2["git.RepoState.Branch"]
        CE3["knowledge.ClusterKnowledge.Load"]
        CE4["knowledge.GetRepoState()"]
        CE5["knowledge.Build()"]
    end

    NL1 -.-> CE1
    NL2 -.-> CE2
    NL3 -.-> CE3
    CE4 --> CE1
    CE4 --> CE2
    CE5 --> CE3

Loading

Sources: internal/git/git.go:42-106, internal/knowledge/context.go:25-61

Testing and Stability

The internal/knowledge package is classified as stable docs/lifecycle.md:69. It maintains high reliability through:

• Nil-Safety: Build handles nil snapshots or state objects by providing empty defaults, preventing panics during partial cluster failures internal/knowledge/context_test.go:55-66.
• Isolation: Tests utilize stubs for the Git subsystem to ensure consistent JSON output regardless of the host environment internal/api/main_test.go:11-18, internal/knowledge/context_test.go:120-130.
• Deterministic Overlay: Unit tests verify that the RAMReservedMB and RAMAllocatableMB fields correctly reflect the delta between raw facts and the reservation ledger internal/knowledge/context_test.go:12-53.

Sources: internal/knowledge/context_test.go:1-143, docs/lifecycle.md:69

---