The Knowledge Layer manages the organization and persistence of concepts in AGISystem2. It builds on the Geometry Layer to store bounded diamonds, manage their evolution through clustering, and enable layered contexts through the theory stack. This layer provides the semantic substrate on which reasoning operates.

ConceptStore

The ConceptStore is the primary repository for concepts. Each concept is identified by a canonical name and stored as one or more bounded diamonds. The store provides fast lookup by name and supports iteration over all stored concepts.

Operations

Operation	Description	Complexity
get(name)	Retrieve concept by canonical name	O(1)
put(name, diamond)	Store or update concept	O(1) amortized
exists(name)	Check if concept exists	O(1)
listConcepts()	Return all concept names	O(N)
delete(name)	Remove concept	O(1)

Concept Structure

Each concept in the store contains:

{
  name: "Dog",                    // Canonical name
  diamonds: [                     // One or more bounded diamonds
    {
      center: Int8Array,          // Centroid vector
      min: Int8Array,             // Per-dimension minimums
      max: Int8Array,             // Per-dimension maximums
      radius: number,             // L1 radius
      mask: Uint8Array,           // Relevance mask
      observationCount: number    // Training observations
    }
  ],
  metadata: {
    created: timestamp,
    lastModified: timestamp,
    source: "assertion" | "inference"
  }
}

ClusterManager

The ClusterManager decides how new observations affect concept shapes. When a new point is observed for a concept, the manager must choose: expand an existing diamond, create a new diamond, or split an overgrown diamond.

Expansion Policy

The expansion policy controls when a diamond grows versus when a new diamond is created. Key parameters:

• maxRadius – Maximum L1 radius before forcing a new cluster
• expansionThreshold – Maximum distance from boundary for expansion
• coherenceCheck – Whether to verify semantic coherence before expansion

function handleObservation(concept, point) {
  // Find nearest diamond
  const nearest = findNearestDiamond(concept.diamonds, point);
  const dist = distanceToSurface(nearest, point);

  if (dist <= 0) {
    // Already inside
    return { action: 'none' };
  }

  if (dist < expansionThreshold && nearest.radius + dist < maxRadius) {
    // Expand existing diamond
    return expandDiamond(nearest, point);
  }

  // Create new diamond
  return createNewDiamond(concept, point);
}

Splitting

When a diamond grows too large or becomes incoherent (covering semantically distant points), it can be split into multiple smaller diamonds. Splitting uses k-means clustering on the observation history to find natural subclusters.

TheoryStack

The TheoryStack enables layered knowledge contexts. Each layer can override specific aspects of concepts without modifying the base knowledge. This mechanism supports:

• Hypothetical reasoning – "What if X were true?"
• Contradictory contexts – Hold conflicting views simultaneously
• Domain-specific overlays – Apply domain knowledge on top of general knowledge
• Undo/rollback – Pop a layer to discard changes

Stack Operations

Operation	Description
push(name)	Create and push new layer with given name
pop()	Remove top layer, discarding its changes
peek()	Get current top layer without removing
depth()	Return current stack depth
compose(conceptName)	Get runtime view of concept through all layers
save(filename)	Persist current top layer to file
load(filename)	Load layer from file and push

Layer Composition

When a concept is requested, the stack composes a runtime view by merging all layers:

function getComposedConcept(name) {
  // Start with base concept
  let result = baseStore.get(name) || createEmpty(name);

  // Apply each layer from bottom to top
  for (const layer of stack) {
    if (layer.has(name)) {
      const override = layer.get(name);
      result = mergeConceptOverride(result, override);
    }
  }

  return result;
}

TheoryLayer

Each TheoryLayer contains concept overrides that modify the base knowledge. Overrides can:

• Add new concepts – Concepts that exist only in this context
• Modify dimensions – Change specific min/max/center values
• Adjust masks – Enable or disable dimensions for comparison
• Change radius – Expand or contract concept boundaries

Override Structure

{
  name: "medical_context",
  overrides: {
    "Aspirin": {
      // New concept added in this layer
      diamonds: [{ center: [...], min: [...], max: [...], radius: 50, mask: [...] }]
    },
    "Inflammation": {
      // Dimension override for existing concept
      dimensionOverrides: {
        42: { min: -20, max: 20 },  // Override dimension 42 bounds
        87: { min: -10, max: 30 }   // Override dimension 87 bounds
      }
    }
  },
  facts: [
    { subject: "Aspirin", relation: "REDUCES", object: "Inflammation" }
  ]
}

Persistence

The Knowledge Layer uses the StorageAdapter to persist concepts and theories. The default adapter writes to the .AGISystem2/ directory structure:

.AGISystem2/
├── data/
│   ├── concepts/
│   │   ├── Dog.bin          # Binary diamond data
│   │   ├── Cat.bin
│   │   └── ...
│   └── index.json           # Name → file mapping
└── theories/
    ├── base.sys2dsl         # Base theory (optional)
    ├── medical_context.sys2dsl
    └── ...

Binary format stores vectors efficiently; text format (.sys2dsl) stores human-readable fact lists for portability and version control.

Configuration

Parameter	auto_test	manual_test	prod
maxRadius	100	150	200
expansionThreshold	30	40	50
maxDiamondsPerConcept	3	5	10
persistenceInterval	immediate	10 ops	100 ops

Related Documentation

• Geometry Layer – The mathematical foundation
• Storage Layer – Persistence details
• Theory Layers Wiki – Background theory
• Theory Syntax – Command syntax for theories