podman/docs/continual-learning/spec.md

Continual Learning Spec

Status: draft
Scope: how PodMan learns team memory from live work and outcomes
Owner: continual learning / Team memory

Purpose

Continual learning is the product proof that PodMan gets more useful from use. It learns team-level coordination memory: ownership, repeated collisions, accepted interventions, dismissed noise, and preferred routing.

The visible loop:

observe -> store -> predict -> outcome -> adapt

Source Collections

engineer_states

Latest per-engineer state from vision and local git.

Key fields:

• podId
• name
• currentFile
• changedFiles
• branch
• confidence
• visionUpdatedAt
• gitUpdatedAt
• updatedAt

observations

Structured perception events.

Key fields:

• podId
• engineerId
• currentFile
• symbol
• activity
• confidence
• observedAt

collisions

Predicted risk events.

Key fields:

• id
• podId
• file
• symbol
• engineers
• severity
• status
• memorySignature
• detectedAt

interventions

Actions PodMan sent or suggested.

Key fields:

• id
• podId
• collisionId
• kind
• channel
• message
• suggestedAction
• createdAt

outcomes

Human or verifier supervision.

Key fields:

• id
• podId
• interventionId
• collisionId
• accepted
• wasRealCollision
• learnedOwner
• recordedAt

team_model

Durable pod memory.

Key fields:

• podId
• graph
• ownership
• collisionSignatures
• interventionPolicy
• updatedAt

memory_vectors

Optional semantic recall. Exact recall comes first.

Key fields:

• podId
• sourceKind
• sourceId
• text
• embedding
• embeddingModel
• tags

Learning Rules

Observe

Write structured evidence from vision, git, GitHub, and agent traces.

Store

Persist source records and materialized summaries. Do not store raw screenshots or recordings.

Predict

Create a collision when multiple engineers converge on the same normalized file or symbol and at least one signal shows active or unpushed work.

Outcome

Record whether the intervention was accepted, dismissed, real, or false.

Adapt

Only accepted real outcomes can create learned_from graph edges. Dismissals adapt suppression, routing, or confidence.

Exact Signature

Use deterministic signatures:

podId:eventType:normalizedFile:symbol:sortedEngineers

Rules:

• Sort engineer names.
• Normalize file paths.
• Use * for missing symbol.
• Never include timestamps.

UI-Facing Loop Snapshot

The graph response may include:

loop
  activeStep
  steps[]
    key
    label
    value
    detail
    status

Step mapping:

Step	Source
Observe	recent observations and git updates
Store	team model, graph records, memory vectors
Predict	open collisions
Outcome	accepted and dismissed outcomes
Adapt	learned owners, learned edges, strategy changes

Activity Stream

The graph response may include:

activity[]
  id
  at
  kind
  title
  detail
  nodeId
  edgeId

Allowed kind values:

editing, collision, intervention, outcome, learned, agent

Acceptance Criteria

• The system can show one accepted outcome changing future memory.
• Exact recall works without vector search.
• The Team memory graph can explain the learning loop.
• Dismissals and false positives are retained.
• The demo does not rely on raw screenshots or hidden state.