How agentralabs/agentic-cognition works
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: write.rs Write engine · mod.rs JSON-RPC protocol · query.rs Query engine · store.rs Model store
Components 21
User interfaces
- CLI
crates/agentic-cognition-cli/src/main.rs - Python API
bindings/python/agentic_cognition/cognition.py - Native FFI
crates/agentic-cognition-ffi/src/lib.rs
MCP server
- MCP stdio server
crates/agentic-cognition-mcp/src/main.rs - JSON-RPC protocol
crates/agentic-cognition-mcp/src/protocol/mod.rs - Tool registry
crates/agentic-cognition-mcp/src/tools/registry.rs - Assistant context sync
crates/agentic-cognition-mcp/src/ghost_bridge.rs
Cognition engine
- Write engine
crates/agentic-cognition/src/engine/write.rs - Query engine
crates/agentic-cognition/src/engine/query.rs - Input validation
crates/agentic-cognition/src/engine/validation.rs - Sister contracts
crates/agentic-cognition/src/contracts.rs - Cognition model types
crates/agentic-cognition/src/types/model.rs
Modeling features
- Belief graph
crates/agentic-cognition/src/types/belief.rs - Belief physics
crates/agentic-cognition/src/inventions/belief_physics.rs - Longitudinal features
crates/agentic-cognition/src/inventions
Persistence and integrations
- Model store
crates/agentic-cognition/src/engine/store.rs - .acog format
crates/agentic-cognition/src/format/mod.rs - Atomic storage
crates/agentic-cognition/src/storage/atomic.rs - Optional sister bridges
crates/agentic-cognition/src/bridges/mod.rs
Other components
- Agent or user
- MCP client
Connections 24
- Agent or user → CLI: issues commands
README.md - Agent or user → Python API: uses API
bindings/python/agentic_cognition/cognition.py - Python API → Native FFI: calls via ctypes
bindings/python/agentic_cognition/cognition.py - Python API → CLI: runs commands
bindings/python/agentic_cognition/cognition.py - MCP client → MCP stdio server: sends requests
README.md - MCP stdio server → JSON-RPC protocol: handles requests
crates/agentic-cognition-mcp/src/main.rs - MCP stdio server → Assistant context sync: syncs context
crates/agentic-cognition-mcp/src/main.rs - JSON-RPC protocol → Tool registry: uses tools
crates/agentic-cognition-mcp/src/protocol/mod.rs - JSON-RPC protocol → Write engine: dispatches writes
crates/agentic-cognition-mcp/src/protocol/mod.rs - JSON-RPC protocol → Query engine: queries models
crates/agentic-cognition-mcp/src/protocol/mod.rs - JSON-RPC protocol → Input validation: validates identifiers
crates/agentic-cognition-mcp/src/protocol/mod.rs - Write engine → Model store: updates models
crates/agentic-cognition/src/engine/write.rs - Write engine → Input validation: validates writes
crates/agentic-cognition/src/engine/write.rs - Write engine → Optional sister bridges: uses bridges
crates/agentic-cognition/src/engine/write.rs - Query engine → Model store: reads models
crates/agentic-cognition/src/engine/query.rs - Query engine → Longitudinal features: uses features
crates/agentic-cognition/src/engine/query.rs - Model store → .acog format: loads and saves
crates/agentic-cognition/src/engine/store.rs - .acog format → Atomic storage: writes atomically
- Write engine → Cognition model types: uses model types
crates/agentic-cognition/src/engine/write.rs - Belief graph → Belief physics: models belief dynamics
- Query engine → Assistant context sync: provides model data
crates/agentic-cognition-mcp/src/ghost_bridge.rs - Sister contracts → Model store: constructs store
crates/agentic-cognition/src/contracts.rs - Sister contracts → Query engine: wraps query engine
crates/agentic-cognition/src/contracts.rs - Sister contracts → Write engine: wraps write engine
crates/agentic-cognition/src/contracts.rs