Knowledge System

Knowledge System

M31 Autonomous (M31A) accumulates project-specific knowledge across sessions, improving code understanding over time. The knowledge system detects coding conventions, observes architectural patterns, learns facts from previous sessions, and tracks per-file intelligence.

Source: internal/workflow/knowledge.go, internal/workflow/knowledge_context.go

Architecture

flowchart TD
    Sessions[Past Sessions] -->|Accumulate| Knowledge[Knowledge Store]
    CodeIntel[Code Intelligence] -->|Detect| Knowledge
    Knowledge -->|FormatContext| LLM[LLM Context]
    Knowledge -->|Reconcile| DCR[Dynamic Context Registry]
    DCR -->|Refresh| CodeIntel

    style Knowledge fill:#e1f5fe
    style LLM fill:#e8f5e9
    style DCR fill:#fff3e0

Loading

Knowledge Types

Convention

Detected coding conventions from file analysis:

type Convention struct {
    Category   string  // e.g., "naming", "structure"
    Pattern    string  // e.g., "snake_case"
    Example    string  // e.g., "my_function_name"
    Confidence float64 // 0.0 - 1.0
}

Detection: DetectConventions(workDir, files) analyzes file naming patterns to identify:

• snake_case (Go, Python default)
• kebab-case (Rust, config files)
• camelCase (JavaScript/TypeScript)
• Package organization patterns

Pattern

Observed architectural patterns:

type Pattern struct {
    Name        string   // e.g., "handler-middleware"
    Description string   // e.g., "HTTP handlers use middleware chains"
    Files       []string // files exhibiting this pattern
    Confidence  float64  // 0.0 - 1.0
}

Fact

Learned facts from previous sessions:

type Fact struct {
    Category  string    // e.g., "dependency", "build", "testing"
    Statement string    // e.g., "Uses go mod vendor for dependencies"
    SessionID string    // originating session
    Timestamp time.Time // when learned
}

FileKnowledge

Per-file metadata:

type FileKnowledge struct {
    Complexity int    // estimated complexity score
    IsTest     bool   // is this a test file?
    IsHot      bool   // frequently modified?
    Language    string // detected language
}

Growth Caps

To prevent unbounded growth, each knowledge type has a maximum count:

Type	Cap	Eviction
Convention	50	Oldest first
Pattern	50	Oldest first
Fact	100	Oldest first
FileKnowledge	200	Oldest first

FormatContext

The FormatContext(maxLen) method renders accumulated knowledge as markdown for injection into the LLM system prompt:

## Project Knowledge

### Conventions
- Naming: snake_case (confidence: 0.95)
- Structure: cmd/internal/pkg layout

### Patterns
- Handler-middleware: HTTP handlers use middleware chains (3 files)

### Facts
- [build] Uses go mod vendor (session abc123)
- [testing] Test files use testdata/ directory (session def456)

Dynamic Context Registry

Source: internal/context/

Bridges the Knowledge system with the code intelligence indexer:

type DynamicContextRegistry struct {
    knowledge      *Knowledge
    indexer        *codeintel.Indexer
    refreshInterval time.Duration  // 5 minutes
    lastRefresh    time.Time
}

Reconciliation

The Reconcile(ctx, snapshot) method:

1. Checks if 5 minutes have elapsed since last refresh
2. Calls DetectConventions() via codeintel if files changed
3. Returns list of ContextChange objects for the TUI

Context Sources

Built-in context sources provide dynamic information to every LLM conversation:

Source	Key	Content
DateTimeSource	core/datetime	Current date/time
EnvironmentSource	core/environment	Working directory, shell, platform
GitSource	core/git	Current branch, last commit
InstructionsSource	core/instructions	AGENTS.md files (global + project)

Each source implements the ContextSource interface:

type ContextSource interface {
    Key() string
    Load(ctx) (string, error)
    Render(value string) string
    RenderUpdate(oldValue, newValue string) string
    RenderRemoval(value string) string
}

Change Detection

The Registry.LoadAll(ctx) method loads all sources concurrently (one goroutine per source). Reconcile(ctx, previous) compares snapshots and returns changes:

ChangeType	Description
ChangeAdded	New context source appeared
ChangeUpdated	Existing source value changed
ChangeRemoved	Source was removed

Changes are emitted as system messages in the TUI, keeping the user informed of context shifts.

Session Persistence

Knowledge is persisted to disk as part of the session state:

• Stored in <project>/.m31a/session.json under the knowledge field
• Loaded on session resume
• Merged with new observations during the session
• Atomic writes via temp-file + rename pattern