The Mirror That Knows You Better Than You Know Yourself
Longitudinal user modeling. Belief physics. Shadow psychology. One file holds your agent's understanding of a human mind.
Quickstart * Problems Solved * How It Works * Belief Physics * Shadow Psychology * Benchmarks * Install * API * Capabilities * Papers
Sister #9 of 25 in the Agentra ecosystem |
.acogformat | 24 Capabilities | 14 MCP Tools | 40+ CLI Commands
Why AgenticCognition
Every conversation starts fresh. The AI doesn't know that you always overthink decisions. Doesn't notice that your confidence exceeds your competence in finance. Can't see that you've been slowly drifting away from the values you proclaimed two years ago.
The current fixes don't work. Chat history is a flat transcript -- you get "what you said," never "who you are." User profiles store static preferences -- never evolving beliefs or unconscious patterns. Provider memory captures facts but never the psychological structure beneath them.
Current AI: Responds to what you SAY. AgenticCognition: Understands who you ARE -- and who you're BECOMING.
AgenticCognition provides longitudinal user modeling -- a living model of human consciousness that evolves with every interaction, detects patterns invisible to the human themselves, tracks drift in beliefs and values over time, maps blindspots and shadow beliefs, simulates how you would think, choose, and react, and projects who you're becoming.
Problems Solved (Read This First)
- Problem: AI forgets who you are between sessions.
Solved: persistent
.acogfiles preserve the living user model -- beliefs, values, patterns, shadows -- surviving restarts, model switches, and long gaps. - Problem: AI responds to your words but misses your patterns. Solved: decision fingerprinting and belief graph analysis detect recurring patterns, biases, and cognitive blind spots.
- Problem: beliefs and values drift silently over time. Solved: drift tracking with value tectonics monitors how your convictions shift, harden, or erode session over session.
- Problem: unconscious biases and shadow beliefs are invisible. Solved: shadow psychology maps projections, defended regions, emotional triggers, and blindspots you cannot see yourself.
- Problem: AI cannot predict how you would react to something new. Solved: preference oracle and decision simulation use your full belief graph to predict reactions before they happen.
- Problem: there is no archaeological record of how someone's thinking evolved. Solved: reasoning fossils, cognitive strata, and growth rings preserve the full history of who you were at every stage.
acog model create
acog belief add $MODEL_ID "I value honesty above all" --domain values --confidence 0.9
acog model soul $MODEL_ID
acog predict decision $MODEL_ID "Accept promotion?" --options "Accept" --options "Decline"
Four commands. A living mirror of a human mind. One .acog file holds everything. Works with Claude, GPT, Ollama, or any LLM you switch to next.
How It Works
Architecture
v0.1.0 -- Longitudinal user modeling infrastructure.
AgenticCognition is a Rust-native cognition engine that treats human understanding as first-class data. Beliefs are living entities with physics. Shadows reveal what the conscious mind conceals. Drift tracks how a person changes over time.
Core Capabilities
- Living User Model -- A continuously evolving representation of a human mind with lifecycle stages from birth through maturity.
- Belief Graph -- Interconnected beliefs with domains, confidence, crystallization, entanglement, and gravity.
- Decision Fingerprint -- Recurring patterns in how a person makes choices, including risk tolerance, time horizon, and decision style.
- Shadow Psychology -- Detection of projections, blindspots, defended regions, and emotional triggers operating below conscious awareness.
- Drift Tracking -- Longitudinal monitoring of how beliefs, values, and identity shift over time.
- Prediction Engine -- Preference oracle, decision simulation, and future projection based on the full model.
- Soul Reflection -- Deep introspective summary of who the person is, synthesized from all model dimensions.
Architecture Overview
+-------------------------------------------------------------+
| YOUR AI AGENT |
| (Claude, Cursor, Windsurf, Cody) |
+----------------------------+--------------------------------+
|
+----------v----------+
| MCP LAYER |
| 14 Tools + stdio |
+----------+----------+
|
+----------------------------v--------------------------------+
| COGNITION ENGINE |
+-----------+-----------+------------+----------+-------------+
| Write | Query | 24 | Belief | Prediction |
| Engine | Engine | Capabilities | Physics | Engine |
+-----------+-----------+------------+----------+-------------+
|
+----------v----------+
| .acog FILE |
| (your user model) |
+---------------------+
Model Lifecycle
Birth -> Infancy (5+ obs) -> Growth (50+ obs) -> Maturity (200+ obs)
|
Crisis -> Rebirth -> Growth
A model begins at Birth with no observations. As data accumulates through the Infancy stage (5+ observations), basic patterns emerge. During Growth (50+ observations), the belief graph densifies and shadows become detectable. At Maturity (200+ observations), the model achieves stable predictive power. A Crisis occurs when the model detects fundamental contradiction or rapid drift, triggering a Rebirth cycle that restructures the belief graph while preserving archaeological layers.
24 Capabilities
AgenticCognition ships 24 capabilities organized across five tiers of increasing depth:
| Tier | Capabilities | Focus |
|---|---|---|
| P0: Living Mirror | Living User Model, Belief Graph, Decision Fingerprint, Soul Reflection | Core consciousness modeling |
| P1: Belief Physics | Crystallization, Self-Concept Topology, Belief Drift, Preference Oracle | Physical properties of beliefs |
| P2: Shadow | Shadow Beliefs, Projections, Blindspots, Bias Field, Emotional Triggers | Unconscious patterns |
| P3: Quantum | Entanglement, Conviction Gravity, Certainty Collapse, Value Tectonics, Metamorphosis | Deep dynamics |
| P4: Temporal | Reasoning Fossils, Cognitive Strata, Decision Simulation, Future Projection, Identity Thread, Growth Rings | Archaeology and prediction |
Full capability documentation ->
Belief Physics
Beliefs are not static strings. They have physical properties that govern how they interact, evolve, and break down over time.
Crystallization
Beliefs harden with repetition and time. A freshly formed belief is malleable -- it can be updated, nuanced, or overturned easily. A belief that has been reinforced across hundreds of interactions becomes crystallized: resistant to change, deeply embedded in the model.
acog belief show $MODEL_ID $BELIEF_ID
# Output:
# {
# "id": "b-042",
# "content": "Hard work leads to success",
# "domain": "world_model",
# "confidence": 0.85,
# "crystallization": 0.73,
# "observations": 147,
# "first_seen": "2024-03-15T...",
# "last_reinforced": "2025-11-20T..."
# }
# Force crystallization calculation
acog belief crystallize $MODEL_ID $BELIEF_ID
Crystallization scale: 0.0 (fluid, easily changed) to 1.0 (diamond-hard, nearly immovable). A crystallization above 0.8 signals a belief so deep it functions more like identity than opinion.
Entanglement
Quantum-linked beliefs change together. When you update one entangled belief, the connected beliefs shift in response. Entanglement captures the hidden correlations in how a person thinks.
acog belief graph $MODEL_ID
# Output shows entangled pairs:
# b-012 "I'm a rational thinker" <--entangled--> b-034 "Emotions cloud judgment"
# b-007 "Family comes first" <--entangled--> b-019 "Career sacrifice is noble"
#
# Entanglement strength: 0.0 (independent) to 1.0 (perfectly correlated)
When "I'm a rational thinker" weakens (perhaps through a series of emotional decisions), "Emotions cloud judgment" automatically weakens too -- because the person's self-concept as hyper-rational is what made them dismiss emotion in the first place.
Conviction Gravity
Strong beliefs warp perception. A belief with high conviction gravity bends how the person interprets new information, pulling ambiguous evidence toward confirmation and pushing contradictory evidence away.
acog belief keystones $MODEL_ID
# Output:
# Keystone beliefs (gravity > 0.7):
# b-003 "I'm smarter than most people" gravity: 0.89
# b-011 "The world is fundamentally fair" gravity: 0.76
# b-022 "Hard work always pays off" gravity: 0.71
High-gravity beliefs are the lens through which everything else is filtered. They are often invisible to the person themselves.
Certainty Collapse
When a keystone belief fails, it triggers a cascade. Connected beliefs lose their anchor and collapse in sequence, like removing a load-bearing wall.
acog belief collapse $MODEL_ID $BELIEF_ID --dry-run
# Output:
# Simulating collapse of b-003 "I'm smarter than most people"
# Direct casualties (entangled, crystallization < 0.5):
# b-015 "My instincts are usually right" collapse probability: 0.82
# b-028 "I don't need others' advice" collapse probability: 0.74
# Indirect casualties (gravity-warped):
# b-041 "Success proves intelligence" cascade probability: 0.61
# Model stability after collapse: 0.43 (crisis threshold: 0.35)
Certainty collapse is the mechanism behind identity crises. The model tracks which beliefs are load-bearing and which are decorative.
Shadow Psychology
The shadow is the part of the psyche that operates below conscious awareness. AgenticCognition's shadow system detects what the person cannot see about themselves.
Shadow Beliefs
Beliefs the person holds but would deny. Detected through behavioral patterns that contradict stated beliefs.
# Output:
# Shadow Map for model m-001:
#
# Shadow Beliefs (inferred, not stated):
# "I fear being ordinary" evidence: 12 observations, confidence: 0.71
# "I don't trust people's motives" evidence: 8 observations, confidence: 0.64
#
# Contradictions (stated vs. behavioral):
# Stated: "I trust my team completely"
# Shadow: Pattern of micromanagement detected (9 instances)
# Contradiction strength: 0.78
Projections
Attributes the person ascribes to others that actually belong to themselves. Detected when criticisms of others mirror the person's own behavioral patterns.
# Output:
# Detected projections:
# "Others are too emotional" <- projects own suppressed emotionality
# Evidence: 6 instances of emotional language in contexts where
# the person claims to be purely rational
Blindspots
Domains where the person's self-assessment diverges most strongly from observed behavior. The gap between who they think they are and who the data says they are.
# Output:
# Blindspot analysis:
# Domain: financial_competence
# Self-assessment: 0.85 ("I'm good with money")
# Observed pattern: 0.42 (impulsive spending, poor risk assessment)
# Gap: 0.43 -- SIGNIFICANT BLINDSPOT
#
# Domain: emotional_intelligence
# Self-assessment: 0.90 ("I'm very empathetic")
# Observed pattern: 0.68 (often misreads social cues)
# Gap: 0.22 -- MODERATE BLINDSPOT
Bias Field and Emotional Triggers
The bias field maps systematic distortions in how the person processes information. Emotional triggers identify stimuli that bypass rational processing and produce automatic reactions.
acog bias triggers $MODEL_ID
Quickstart
Living mirror in 7 commands
acog model create
# { "model_id": "550e8400-e29b-41d4-a716-446655440000", "status": "created", "stage": "birth" }
# 2. Add beliefs across domains
acog belief add $MODEL_ID "I value honesty above all" --domain values --confidence 0.9
acog belief add $MODEL_ID "Hard work leads to success" --domain world_model --confidence 0.7
acog belief add $MODEL_ID "I'm good at problem-solving" --domain capability --confidence 0.8
acog belief add $MODEL_ID "People are generally trustworthy" --domain world_model --confidence 0.6
# 3. Connect entangled beliefs
acog belief connect $MODEL_ID $BELIEF_1 $BELIEF_2 --strength 0.7
# 4. View the belief graph
acog belief graph $MODEL_ID
# Nodes: 4, Edges: 1, Domains: [values, world_model, capability]
# Crystallization avg: 0.12, Keystones: 0
# 5. Get the full model portrait
acog model portrait $MODEL_ID
# Living User Model Portrait
# Stage: infancy (4 observations)
# Belief count: 4
# Domains: values, world_model, capability
# Shadow detected: none (insufficient data)
# Drift: no baseline established
# 6. Perform a soul reflection
acog model soul $MODEL_ID
# Soul Reflection:
# "An emerging model of someone who places honesty at the center of their
# value system, believes in meritocratic outcomes, and has confidence in
# their analytical abilities. The world is viewed as broadly trustworthy.
# Insufficient data for shadow analysis or drift detection."
# 7. Predict a preference
acog predict preference $MODEL_ID "remote work opportunity"
# Preference prediction:
# Alignment with values: 0.62
# Alignment with world_model: 0.58
# Predicted preference: MODERATE POSITIVE
# Key factors: autonomy (aligns with self-reliance beliefs),
# trust (remote work requires trust assumption)
Simulate a decision
--options "Accept" --options "Decline" --options "Negotiate hybrid role"
# Decision Simulation:
# Option 1: "Accept" -- alignment: 0.54
# Pro: aligns with "hard work leads to success"
# Con: management may conflict with "problem-solving" self-concept
# Option 2: "Decline" -- alignment: 0.38
# Low alignment: declining contradicts achievement orientation
# Option 3: "Negotiate hybrid role" -- alignment: 0.71
# Best fit: preserves problem-solving identity while honoring achievement drive
# Predicted choice: Option 3 (0.71)
Project future self
# Future Projection (180 days):
# Belief drift forecast:
# "Hard work leads to success" -- likely to crystallize further (+0.08)
# "People are generally trustworthy" -- at risk of erosion if negative events occur
# Identity trajectory: stable growth phase
# Shadow forecast: insufficient data for shadow projection
Cross-session continuity
acog model create
acog belief add $MODEL_ID "I'm a careful decision-maker" --domain self_concept --confidence 0.8
# Session 47 -- months later, different LLM, same file:
acog model portrait $MODEL_ID # Full model preserved
acog drift timeline $MODEL_ID # See how beliefs shifted over months
acog shadow map $MODEL_ID # Shadow has deepened with more data
acog pattern fingerprint $MODEL_ID # Decision patterns extracted
Common Workflows
The following examples show the most common patterns for using AgenticCognition via the CLI and MCP server.
acog heartbeat --belief "User prefers Rust for performance-critical code"
# Query the living model -- retrieve beliefs matching a pattern
acog query --filter "language preferences" --top 10
# Detect shadow patterns -- find projections, blindspots, defended regions
acog shadow --detect projections blindspots defended-regions
# Check belief drift -- see which beliefs have shifted over time
acog drift --since "30 days" --threshold 0.15
# Run a decision simulation -- predict how the user will approach a problem
acog predict --scenario "choosing between two job offers" --depth 3
# Export the living model to a portable .acog file
acog export --output ~/my-model.acog
# Load a .acog model file into the engine
acog import --input ~/my-model.acog
# Start the MCP server for Claude/Cursor integration
agentic-cognition-mcp --storage ~/.cognition serve
# Inspect growth rings -- see strata of belief evolution over time
acog rings --year 2025 --strata all
# Get current coherence score and model health
acog status
MCP Server
Any MCP-compatible client gets instant access to persistent user modeling. The agentic-cognition-mcp crate exposes the full CognitionEngine over the Model Context Protocol (JSON-RPC 2.0 over stdio).
14 MCP Tools
| Tool | Description |
|---|---|
cognition_model_create |
Create a new living user model |
cognition_model_heartbeat |
Pulse model with new observations |
cognition_model_vitals |
Get model health and vital signs |
cognition_model_portrait |
Get full model portrait |
cognition_belief_add |
Add a new belief to the model |
cognition_belief_query |
Query beliefs by domain or search |
cognition_belief_graph |
Get belief graph with connections |
cognition_soul_reflect |
Perform deep soul reflection |
cognition_self_topology |
Get self-concept topology |
cognition_pattern_fingerprint |
Get decision fingerprint |
cognition_shadow_map |
Get shadow map |
cognition_drift_track |
Track belief drift over time |
cognition_predict |
Predict user preference |
cognition_simulate |
Simulate user decision |
Configure Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
"mcpServers": {
"agentic-cognition": {
"command": "acog-mcp",
"args": ["--storage", "~/.agentic/cognition"]
}
}
}
Zero-config: defaults to
~/.agentic/cognition. Override with"args": ["--storage", "/path/to/storage"].
Configure VS Code / Cursor
Add to .vscode/settings.json:
"mcp.servers": {
"agentic-cognition": {
"command": "acog-mcp",
"args": ["--storage", "~/.agentic/cognition"]
}
}
}
Configure Claude Code
Add to ~/.claude/settings.json:
"mcpServers": {
"agentic-cognition": {
"command": "acog-mcp",
"args": []
}
}
}
Example MCP Conversation
Once the MCP server is connected, the LLM naturally uses cognition tools:
User: "I've been thinking about switching careers to data science"
LLM internally calls: cognition_model_heartbeat
{ "model_id": "m-001", "observation": "Considering career switch to data science" }
LLM internally calls: cognition_predict
{ "model_id": "m-001", "query": "career change to data science" }
LLM response: "Based on your model, this aligns well with your problem-solving
self-concept (0.8 confidence) and your belief in hard work leading to success.
However, I notice a potential shadow pattern -- your last three major decisions
involved choosing the intellectually stimulating option even when a simpler
path existed. You might want to check whether this is genuine passion or
pattern-driven novelty seeking."
