| status | stable |
|---|
AgenticCognition exposes its functionality through four primary surfaces: the Rust library API, the MCP server, the CLI, and C FFI bindings.
The core library (agentic-cognition crate) provides two primary engine types and supporting modules.
All mutation operations for the living user model.
| Method | Description |
|---|---|
create_model(name: Option<&str>) |
Create a new living user model |
heartbeat(model_id, context) |
Record an interaction heartbeat |
add_belief(model_id, text, domain, confidence) |
Add a belief to the model |
strengthen_belief(model_id, belief_id, evidence) |
Increase belief confidence |
weaken_belief(model_id, belief_id, evidence) |
Decrease belief confidence |
connect_beliefs(model_id, a, b, rel_type) |
Create an entanglement link |
crystallize_belief(model_id, belief_id) |
Force-crystallize a belief |
collapse_belief(model_id, belief_id) |
Trigger belief collapse |
delete_model(model_id) |
Delete a model and its data |
All read operations for the living user model.
| Method | Description |
|---|---|
vitals(model_id) |
Model health metrics and activity summary |
portrait(model_id, depth) |
Natural-language portrait of the user |
soul_reflect(model_id, focus) |
Deep soul reflection across all dimensions |
belief_query(model_id, query, domain, min_confidence) |
Query beliefs by text, domain, or property |
belief_graph(model_id, depth, center) |
Full belief graph with entanglements |
keystones(model_id) |
Identify keystone beliefs |
contradictions(model_id) |
Detect contradictory belief pairs |
self_topology(model_id) |
Self-concept topology map |
pattern_fingerprint(model_id, domain) |
Decision-making fingerprint |
shadow_map(model_id) |
Shadow map with projections and blindspots |
drift_track(model_id, range, domain) |
Longitudinal drift analysis |
predict(model_id, query) |
Preference prediction |
simulate(model_id, scenario, options) |
Decision simulation |
consciousness_map(model_id) |
Consciousness region activity |
list_models() |
List all models in storage |
Storage abstraction for .acog file persistence.
| Method | Description |
|---|---|
new(path) |
Create a store at the given directory path |
save(model) |
Write model to .acog file with BLAKE3 integrity |
load(model_id) |
Load model from .acog file with integrity check |
delete(model_id) |
Delete model file |
list() |
List all model IDs in the store |
Direct file I/O for .acog format.
| Method | Description |
|---|---|
write(path, model) |
Write model to file with atomic temp-rename |
read(path) |
Read model from file with BLAKE3 verification |
verify(path) |
Verify file integrity without loading |
All 14 MCP tools are accessible through agentic-cognition-mcp over JSON-RPC 2.0 stdio transport. See MCP Tools for full parameter tables and response formats.
| Tool | Operation |
|---|---|
cognition_model_create |
Create a new living user model |
cognition_model_heartbeat |
Record an interaction heartbeat |
cognition_model_vitals |
Retrieve model health metrics |
cognition_model_portrait |
Generate natural-language portrait |
cognition_belief_add |
Add a belief to the model |
cognition_belief_query |
Query beliefs |
cognition_belief_graph |
Retrieve belief graph |
cognition_soul_reflect |
Deep soul reflection |
cognition_self_topology |
Self-concept topology |
cognition_pattern_fingerprint |
Decision fingerprint |
cognition_shadow_map |
Shadow map |
cognition_drift_track |
Drift tracking |
cognition_predict |
Preference prediction |
cognition_simulate |
Decision simulation |
The acog binary provides 40+ commands organized into groups. See CLI Reference for complete command documentation.
| Group | Commands | Purpose |
|---|---|---|
| model | 9 | Model lifecycle management |
| belief | 12 | Belief graph operations |
| self | 6 | Self-concept topology |
| pattern | 3 | Behavioral pattern analysis |
| shadow | 3 | Shadow psychology mapping |
| bias | 2 | Cognitive bias detection |
| drift | 2 | Longitudinal drift tracking |
| predict | 3 | Prediction engine |
The agentic-cognition-ffi crate exposes a C-compatible FFI surface. See FFI Reference for the complete header file and memory management rules.
Available bindings:
| Language | Package |
|---|---|
| Python | pip install agentic-cognition |
| Node.js / WASM | npm/wasm package directory |
| C / C++ | agentic_cognition_ffi.h header |
| Swift | Via C FFI bridge |
| Go | Via cgo with C header |