# heraclitus0/cognize architecture

> Architecture diagram of the GitHub repository heraclitus0/cognize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heraclitus0/cognize
- Repository: https://github.com/heraclitus0/cognize

## Overview

Cognize is a programmable cognition engine: a system supplies evidence, optionally through multimodal perception, and an epistemic state updates belief, drift, memory, and rupture status. Policies customize those updates; meta-policy selection and bounded evolution adapt policy behavior. Graphs coordinate multiple states and can apply programmable influence. The excerpts show the kernel’s policy machinery, perception encoders, and graph stepping, but omit substantial implementation details; documented capabilities are included without inferring unshown internal calls.

Main entry points: [`cognize/epistemic.py`](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py) (Epistemic state), [`cognize/network.py`](https://github.com/heraclitus0/cognize/blob/main/cognize/network.py) (Epistemic graph), [`cognize/perception.py`](https://github.com/heraclitus0/cognize/blob/main/cognize/perception.py) (Perception fusion), [`cognize/meta_learning.py`](https://github.com/heraclitus0/cognize/blob/main/cognize/meta_learning.py) (Evolution bounds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Evidence input"]
  node_perception["Perception fusion<br/>[perception.py]"]
  node_encoders["Custom encoders"]
end

subgraph group_kernel["Epistemic kernel"]
  node_state["Epistemic state<br/>[epistemic.py]"]
  node_telemetry["State telemetry<br/>[epistemic.py]"]
end

subgraph group_adapt["Policy adaptation"]
  node_policies["Policy presets<br/>[policies.py]"]
  node_manager["Meta-policy manager<br/>[epistemic.py]"]
  node_policy_memory["Policy memory<br/>[epistemic.py]"]
  node_shadow["Shadow evaluation<br/>[epistemic.py]"]
  node_bounds["Evolution bounds<br/>[meta_learning.py]"]
end

subgraph group_graphs["Graph coordination"]
  node_graph["Epistemic graph<br/>[network.py]"]
  node_edge_strategies["Programmable edges<br/>[network.py]"]
  node_graph_trace["Cascade traces<br/>[network.py]"]
end

node_caller(("Host system"))
node_consumer(("Application consumer"))

node_caller -->|"supplies inputs"| node_perception
node_caller -->|"supplies evidence"| node_state
node_perception -->|"calls encoders"| node_encoders
node_perception -->|"provides vector"| node_state
node_state -->|"uses injected policies"| node_policies
node_state -->|"selects policies"| node_manager
node_manager -->|"evaluates candidates"| node_shadow
node_manager -->|"records rewards"| node_policy_memory
node_bounds -->|"sets evolution bounds"| node_manager
node_graph -->|"steps graph nodes"| node_state
node_graph -->|"applies edge strategies"| node_edge_strategies
node_graph -->|"records cascades"| node_graph_trace
node_state -->|"exports state history"| node_telemetry
node_state -->|"returns state results"| node_consumer
node_graph -->|"returns graph results"| node_consumer

click node_perception "https://github.com/heraclitus0/cognize/blob/main/cognize/perception.py"
click node_state "https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py"
click node_telemetry "https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py"
click node_policies "https://github.com/heraclitus0/cognize/blob/main/cognize/policies.py"
click node_manager "https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py"
click node_policy_memory "https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py"
click node_shadow "https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py"
click node_bounds "https://github.com/heraclitus0/cognize/blob/main/cognize/meta_learning.py"
click node_graph "https://github.com/heraclitus0/cognize/blob/main/cognize/network.py"
click node_edge_strategies "https://github.com/heraclitus0/cognize/blob/main/cognize/network.py"
click node_graph_trace "https://github.com/heraclitus0/cognize/blob/main/cognize/network.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_perception,node_encoders toneBlue
class node_state,node_telemetry toneAmber
class node_policies,node_manager,node_policy_memory,node_shadow,node_bounds toneMint
class node_graph,node_edge_strategies,node_graph_trace toneRose
class node_caller,node_consumer toneIndigo
```

## Components

### Evidence input

- [Perception fusion](https://github.com/heraclitus0/cognize/blob/main/cognize/perception.py): `cognize/perception.py`
- **Custom encoders**

### Epistemic kernel

- [Epistemic state](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py): `cognize/epistemic.py`
- [State telemetry](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py): `cognize/epistemic.py`

### Policy adaptation

- [Policy presets](https://github.com/heraclitus0/cognize/blob/main/cognize/policies.py): `cognize/policies.py`
- [Meta-policy manager](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py): `cognize/epistemic.py`
- [Policy memory](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py): `cognize/epistemic.py`
- [Shadow evaluation](https://github.com/heraclitus0/cognize/blob/main/cognize/epistemic.py): `cognize/epistemic.py`
- [Evolution bounds](https://github.com/heraclitus0/cognize/blob/main/cognize/meta_learning.py): `cognize/meta_learning.py`

### Graph coordination

- [Epistemic graph](https://github.com/heraclitus0/cognize/blob/main/cognize/network.py): `cognize/network.py`
- [Programmable edges](https://github.com/heraclitus0/cognize/blob/main/cognize/network.py): `cognize/network.py`
- [Cascade traces](https://github.com/heraclitus0/cognize/blob/main/cognize/network.py): `cognize/network.py`

### Other components

- **Host system**
- **Application consumer**

## Connections

- Host system → Perception fusion: supplies inputs (evidence: `README.md`)
- Host system → Epistemic state: supplies evidence (evidence: `README.md`)
- Perception fusion → Custom encoders: calls encoders (evidence: `cognize/perception.py`)
- Perception fusion → Epistemic state: provides vector (evidence: `README.md`)
- Epistemic state → Policy presets: uses injected policies (evidence: `README.md`)
- Epistemic state → Meta-policy manager: selects policies (evidence: `cognize/epistemic.py`)
- Meta-policy manager → Shadow evaluation: evaluates candidates (evidence: `cognize/epistemic.py`)
- Meta-policy manager → Policy memory: records rewards (evidence: `cognize/epistemic.py`)
- Evolution bounds → Meta-policy manager: sets evolution bounds (evidence: `cognize/meta_learning.py`)
- Epistemic graph → Epistemic state: steps graph nodes (evidence: `README.md`)
- Epistemic graph → Programmable edges: applies edge strategies (evidence: `README.md`)
- Epistemic graph → Cascade traces: records cascades (evidence: `README.md`)
- Epistemic state → State telemetry: exports state history (evidence: `README.md`)
- Epistemic state → Application consumer: returns state results (evidence: `README.md`)
- Epistemic graph → Application consumer: returns graph results (evidence: `README.md`)
