MAXIM
Tools & Introspection
How the Agent Acts and Reflects
Tools are the only way Maxim's LLM agent performs side effects. Every tool call passes through the FearAgent for safety review before execution. But tools aren't just for acting on the world — Maxim also has introspection tools that let the agent query its own biological subsystems: memories, causal predictions, pain history, temporal patterns, and energy state.
Contents
- Action Tools (Side Effects)
- Introspection Tools (Self-Awareness)
- Memory: Episodic Recall & Similarity
- Causal: Prediction & Learned Links
- Pain & Fear: Aversive Self-Awareness
- Temporal: Circadian Patterns
- Semantic: Concepts & Relationships
- Scene & Energy: Perception and Budget
- Learned Tool Index
- Tool Safety
Action Tools
These tools let the agent interact with the world — moving the robot, reading files, executing code, and communicating with humans.
Robot Control
move track_target focus_interests novelty_track
Head movement, object tracking, interest-driven attention. No-op stubs in headless mode.
Filesystem
read_file write_file edit_file glob bash
Sandboxed by mode (passive/active/singularity). edit_file supports context_before/context_after disambiguation.
Code & Git
search_code run_tests git_diff git_commit
Regex code search, pytest execution with structured results, git operations.
Communication
respond speak send_message call_user
Console output, TTS, SMS/voice via Twilio gateway.
Introspection Tools
These are read-only tools that let the LLM query its own biological subsystems. They give the agent self-awareness — the ability to ask "what do I remember?", "what will happen if I do this?", "have I been hurt by this before?", and "how much energy have I used?"
Design Principles
- Read-only. No introspection tool modifies agent state.
- Bounded output. All tools accept a
limitparameter to control context cost. - Graceful degradation. In headless mode, vision tools return
{"available": false}instead of crashing. - Formatted for LLM. Returns structured dicts the LLM can reason about, not raw data dumps.
Memory: Episodic Recall & Similarity
The hippocampus stores every agentic loop as an episodic memory (perceive → decide → act → evaluate). The entorhinal cortex (EC) indexes them for multi-modal similarity search. These tools let the LLM explore both.
memory_recall
Search episodic memories. Filter by goal, tool, success/failure, detected objects, people, mode, or time range. Use expand=true to find associated memories via spreading activation through ASSOCIATES and CAUSES edges.
Biological analog: Hippocampal recall with spreading activation through the associative memory graph. ASSOCIATES edges form during memory capture (perceptual overlap). CAUSES edges form when NAc detects surprising outcomes (RPE > 0.3).
similarity_search
Find situations similar to a past experience using the EC's LSH approximate nearest neighbor. Multi-modal matching: structural hash, temporal bins, semantic embedding, and context match.
Biological analog: The entorhinal cortex is the gateway to the hippocampus. It transforms multi-modal input into a common similarity space for fast pattern matching.
Causal: Prediction & Learned Links
The nucleus accumbens (NAc) learns cause-effect relationships via Rescorla-Wagner learning. Every tool execution updates a causal link with a prediction error (RPE). These tools let the LLM consult this learned model before acting.
predict_outcome
Ask the NAc what will happen if you execute a tool. Returns the predicted value (0=bad, 1=good), expected outcome valence, expected delay with confidence interval, and all possible outcomes.
Biological analog: Dopaminergic prediction in the mesolimbic pathway. The NAc computes reward prediction error (RPE) — the difference between expected and actual outcomes — to learn which actions lead to which results in which contexts.
causal_links
Inspect the raw cause-effect database. Query by event signature, outcome signature, contributing memory ID, or valence filter. See confidence, observation count, temporal delay distributions, and which memories informed each link.
Pain & Fear: Aversive Self-Awareness
The PainDetector converts tool errors and movement failures into escalating pain signals. The FearAgent gates actions before execution. Together they implement an aversive learning system that teaches the agent what to avoid.
pain_history
Check pain signal statistics and optionally test whether the FearAgent would block a specific action. Shows counts by pain type (tool failure, timeout, movement error, direction thrashing).
Biological analog: Nociception (pain detection) and the amygdala (fear conditioning). Repeated tool failures increase pain intensity, driving NAc learning and FearAgent gating — like how repeated burns teach you to avoid the stove.
Temporal: Circadian Patterns
The SCN (suprachiasmatic nucleus) bins every memory by hour-of-day, day-of-week, week-of-month, and month. This lets the agent discover rhythmic patterns in its own activity.
temporal_patterns
Find memories from specific times of day or days of week. Use discover_rhythms=true to find recurring patterns — for example, that API failures cluster during peak hours.
Biological analog: The SCN in the hypothalamus is the body's master clock. It synchronizes circadian rhythms by tracking environmental time cues. Maxim's SCN enables temporal pattern learning across sessions.
Semantic: Concepts & Relationships
The anterior temporal lobe (ATL) stores semantic concepts with typed relationships (IS_A, PART_OF, CAUSES, EXECUTES_WITH). The LLM can query this knowledge base to ground its reasoning.
concept_query
Search concepts by name or category. Explore typed relationships between concepts. Discover which skills are associated with which objects via EXECUTES_WITH edges.
Biological analog: The ATL is the brain's semantic hub. Patients with ATL damage lose category-level knowledge ("what IS a cup?") while retaining episodic memories ("I drank from one yesterday"). Maxim's ATL captures these generalizations across episodes.
Scene & Energy: Perception and Budget
scene_summary
Get the current visual scene: most salient objects with novelty scores, current gaze focus, dwell time, and suggested next attention target. Only available when vision is active (not in headless mode).
energy_status
Check computational resource consumption: token usage, inference costs, and energy rate over a configurable time window.
system_stats
Aggregate health check across all subsystems in one call. Returns hippocampus memory counts, NAc causal link counts, EC signature counts, ATL concept counts, energy totals, pain signal counts, and significance learner weights.
Learned Tool Index
With 20+ tools, dumping every schema into the LLM prompt wastes hundreds of tokens. The LearnedToolIndex is a keyword-weighted hashtable that learns which tools are relevant to which goals, saving ~74% of tool-context tokens per prompt.
How it works
- Auto-extraction: Keywords extracted from each tool's name, description, and parameters at startup.
- Scoring: Goal text is tokenized and matched against the index. Matched tools get full schemas (CRITICAL priority), unmatched get name-only (NICE_TO_HAVE, dropped under token pressure).
- Learning: On tool success, matched keyword weights strengthen and new keywords are discovered from goal text. On tool surfaced-but-unused, keyword weights decay. Failure does NOT weaken keywords (tool failure ≠ wrong tool).
- Persistence: Learned weights saved across sessions to
data/memory/tool_index.json.
Tool Safety
Every tool call passes through the FearAgent before execution. FearAgent uses:
- Deterministic pattern matching — regex for known dangerous patterns (shell injection, path traversal, etc.)
- LLM review (if available) — nuanced safety assessment for ambiguous cases
- NAc prediction — the AdaptivePolicy blocks actions with very high-confidence negative predictions (confidence > 0.85, value < 0.1)
Introspection tools bypass FearAgent since they're read-only — they can't cause harm. The agent can freely query its own memories, predictions, and pain history without safety gating.