# agentralabs/agentic-cognition architecture

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

- Interactive diagram: https://gitdiagram.com/agentralabs/agentic-cognition
- Repository: https://github.com/agentralabs/agentic-cognition

## Overview

AgenticCognition is a Rust-native, persistent model of a person’s beliefs, patterns, shadows, and changes over time. The principal workflow is to create a model, add observations such as beliefs, then query or reflect on the evolving model through the CLI or MCP tools; the engine persists it in the .acog format. The README also describes prediction, drift tracking, shadow psychology, and assistant-context syncing. Some feature modules are unsampled, so their presence is documented, but their internal call paths are not inferred.

Main entry points: [`crates/agentic-cognition/src/engine/write.rs`](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/write.rs) (Write engine), [`crates/agentic-cognition-mcp/src/protocol/mod.rs`](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/protocol/mod.rs) (JSON-RPC protocol), [`crates/agentic-cognition/src/engine/query.rs`](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/query.rs) (Query engine), [`crates/agentic-cognition/src/engine/store.rs`](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/store.rs) (Model store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[main.rs]"]
  node_python["Python API<br/>[cognition.py]"]
  node_ffi["Native FFI<br/>[lib.rs]"]
end

subgraph group_mcp["MCP server"]
  node_mcp_main["MCP stdio server<br/>[main.rs]"]
  node_protocol["JSON-RPC protocol<br/>[mod.rs]"]
  node_tool_registry["Tool registry<br/>[registry.rs]"]
  node_ghost["Assistant context sync<br/>[ghost_bridge.rs]"]
end

subgraph group_engine["Cognition engine"]
  node_write["Write engine<br/>[write.rs]"]
  node_query["Query engine<br/>[query.rs]"]
  node_validation["Input validation<br/>[validation.rs]"]
  node_contracts["Sister contracts<br/>[contracts.rs]"]
  node_types["Cognition model types<br/>[model.rs]"]
end

subgraph group_modeling["Modeling features"]
  node_beliefs["Belief graph<br/>[belief.rs]"]
  node_physics["Belief physics<br/>[belief_physics.rs]"]
  node_other_features["Longitudinal features"]
end

subgraph group_persistence["Persistence and integrations"]
  node_store[("Model store<br/>[store.rs]")]
  node_format[".acog format<br/>[mod.rs]"]
  node_storage["Atomic storage<br/>[atomic.rs]"]
  node_bridges["Optional sister bridges<br/>[mod.rs]"]
end

node_user(("Agent or user"))
node_mcp_client(("MCP client"))

node_user -->|"issues commands"| node_cli
node_user -->|"uses API"| node_python
node_python -->|"calls via ctypes"| node_ffi
node_python -->|"runs commands"| node_cli
node_mcp_client -->|"sends requests"| node_mcp_main
node_mcp_main -->|"handles requests"| node_protocol
node_mcp_main -->|"syncs context"| node_ghost
node_protocol -->|"uses tools"| node_tool_registry
node_protocol -->|"dispatches writes"| node_write
node_protocol -->|"queries models"| node_query
node_protocol -->|"validates identifiers"| node_validation
node_write -->|"updates models"| node_store
node_write -->|"validates writes"| node_validation
node_write -->|"uses bridges"| node_bridges
node_query -->|"reads models"| node_store
node_query -->|"uses features"| node_other_features
node_store -->|"loads and saves"| node_format
node_format -.->|"writes atomically"| node_storage
node_write -->|"uses model types"| node_types
node_beliefs -.->|"models belief dynamics"| node_physics
node_query -->|"provides model data"| node_ghost
node_contracts -->|"constructs store"| node_store
node_contracts -.->|"wraps query engine"| node_query
node_contracts -.->|"wraps write engine"| node_write

click node_cli "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-cli/src/main.rs"
click node_python "https://github.com/agentralabs/agentic-cognition/blob/main/bindings/python/agentic_cognition/cognition.py"
click node_ffi "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-ffi/src/lib.rs"
click node_mcp_main "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/main.rs"
click node_protocol "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/protocol/mod.rs"
click node_tool_registry "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/tools/registry.rs"
click node_ghost "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/ghost_bridge.rs"
click node_write "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/write.rs"
click node_query "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/query.rs"
click node_validation "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/validation.rs"
click node_contracts "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/contracts.rs"
click node_types "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/types/model.rs"
click node_beliefs "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/types/belief.rs"
click node_physics "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/inventions/belief_physics.rs"
click node_other_features "https://github.com/agentralabs/agentic-cognition/tree/main/crates/agentic-cognition/src/inventions"
click node_store "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/store.rs"
click node_format "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/format/mod.rs"
click node_storage "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/storage/atomic.rs"
click node_bridges "https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/bridges/mod.rs"

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_cli,node_python,node_ffi,node_user,node_mcp_client toneBlue
class node_mcp_main,node_protocol,node_tool_registry,node_ghost toneAmber
class node_write,node_query,node_validation,node_contracts,node_types toneMint
class node_beliefs,node_physics,node_other_features toneRose
class node_store,node_format,node_storage,node_bridges toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-cli/src/main.rs): `crates/agentic-cognition-cli/src/main.rs`
- [Python API](https://github.com/agentralabs/agentic-cognition/blob/main/bindings/python/agentic_cognition/cognition.py): `bindings/python/agentic_cognition/cognition.py`
- [Native FFI](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-ffi/src/lib.rs): `crates/agentic-cognition-ffi/src/lib.rs`

### MCP server

- [MCP stdio server](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/main.rs): `crates/agentic-cognition-mcp/src/main.rs`
- [JSON-RPC protocol](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/protocol/mod.rs): `crates/agentic-cognition-mcp/src/protocol/mod.rs`
- [Tool registry](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/tools/registry.rs): `crates/agentic-cognition-mcp/src/tools/registry.rs`
- [Assistant context sync](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition-mcp/src/ghost_bridge.rs): `crates/agentic-cognition-mcp/src/ghost_bridge.rs`

### Cognition engine

- [Write engine](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/write.rs): `crates/agentic-cognition/src/engine/write.rs`
- [Query engine](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/query.rs): `crates/agentic-cognition/src/engine/query.rs`
- [Input validation](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/validation.rs): `crates/agentic-cognition/src/engine/validation.rs`
- [Sister contracts](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/contracts.rs): `crates/agentic-cognition/src/contracts.rs`
- [Cognition model types](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/types/model.rs): `crates/agentic-cognition/src/types/model.rs`

### Modeling features

- [Belief graph](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/types/belief.rs): `crates/agentic-cognition/src/types/belief.rs`
- [Belief physics](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/inventions/belief_physics.rs): `crates/agentic-cognition/src/inventions/belief_physics.rs`
- [Longitudinal features](https://github.com/agentralabs/agentic-cognition/tree/main/crates/agentic-cognition/src/inventions): `crates/agentic-cognition/src/inventions`

### Persistence and integrations

- [Model store](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/engine/store.rs): `crates/agentic-cognition/src/engine/store.rs`
- [.acog format](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/format/mod.rs): `crates/agentic-cognition/src/format/mod.rs`
- [Atomic storage](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/storage/atomic.rs): `crates/agentic-cognition/src/storage/atomic.rs`
- [Optional sister bridges](https://github.com/agentralabs/agentic-cognition/blob/main/crates/agentic-cognition/src/bridges/mod.rs): `crates/agentic-cognition/src/bridges/mod.rs`

### Other components

- **Agent or user**
- **MCP client**

## Connections

- Agent or user → CLI: issues commands (evidence: `README.md`)
- Agent or user → Python API: uses API (evidence: `bindings/python/agentic_cognition/cognition.py`)
- Python API → Native FFI: calls via ctypes (evidence: `bindings/python/agentic_cognition/cognition.py`)
- Python API → CLI: runs commands (evidence: `bindings/python/agentic_cognition/cognition.py`)
- MCP client → MCP stdio server: sends requests (evidence: `README.md`)
- MCP stdio server → JSON-RPC protocol: handles requests (evidence: `crates/agentic-cognition-mcp/src/main.rs`)
- MCP stdio server → Assistant context sync: syncs context (evidence: `crates/agentic-cognition-mcp/src/main.rs`)
- JSON-RPC protocol → Tool registry: uses tools (evidence: `crates/agentic-cognition-mcp/src/protocol/mod.rs`)
- JSON-RPC protocol → Write engine: dispatches writes (evidence: `crates/agentic-cognition-mcp/src/protocol/mod.rs`)
- JSON-RPC protocol → Query engine: queries models (evidence: `crates/agentic-cognition-mcp/src/protocol/mod.rs`)
- JSON-RPC protocol → Input validation: validates identifiers (evidence: `crates/agentic-cognition-mcp/src/protocol/mod.rs`)
- Write engine → Model store: updates models (evidence: `crates/agentic-cognition/src/engine/write.rs`)
- Write engine → Input validation: validates writes (evidence: `crates/agentic-cognition/src/engine/write.rs`)
- Write engine → Optional sister bridges: uses bridges (evidence: `crates/agentic-cognition/src/engine/write.rs`)
- Query engine → Model store: reads models (evidence: `crates/agentic-cognition/src/engine/query.rs`)
- Query engine → Longitudinal features: uses features (evidence: `crates/agentic-cognition/src/engine/query.rs`)
- Model store → .acog format: loads and saves (evidence: `crates/agentic-cognition/src/engine/store.rs`)
- .acog format → Atomic storage: writes atomically
- Write engine → Cognition model types: uses model types (evidence: `crates/agentic-cognition/src/engine/write.rs`)
- Belief graph → Belief physics: models belief dynamics
- Query engine → Assistant context sync: provides model data (evidence: `crates/agentic-cognition-mcp/src/ghost_bridge.rs`)
- Sister contracts → Model store: constructs store (evidence: `crates/agentic-cognition/src/contracts.rs`)
- Sister contracts → Query engine: wraps query engine (evidence: `crates/agentic-cognition/src/contracts.rs`)
- Sister contracts → Write engine: wraps write engine (evidence: `crates/agentic-cognition/src/contracts.rs`)
