brain.* tools

8 cognitive tools — orientation, thinking, recall, calibration, health, and graph queries.

The brain.* namespace is for AI agents with persistent identity. These tools compound over time: the more an agent uses them, the better its context becomes.

When to use brain. vs memory.:** Use brain.* when the agent has a persistent identity and you want expertise tracking, model continuity, and calibration. Use memory.* for simple knowledge storage without agent identity.

brain.orient

Call once at the start of every session. Returns everything the agent needs to resume work: identity, galaxy context, working state, knowledge, and operating protocol.

agent_name     string, required   Persistent agent identifier
model          string, required   Current model (e.g., "claude-sonnet-4-6")
agent_type     string, optional   GENERAL | SPECIALIST (default: GENERAL)
active_planet  string, optional   Planet to orient in
active_biome   string, optional   Biome to orient in
max_tokens     int, optional      Token budget for context

Response includes:

{
  "session_id": "sess-abc",
  "agent_identity": {
    "total_sessions": 47,
    "expertise": [{"domain": "FastAPI", "level": 0.87}]
  },
  "transition_brief": null,
  "operating_protocol": {
    "session_start_instruction": "Call brain.orient to load context"
  }
}

When a model switch is detected, transition_brief contains a structured handoff from the previous model.

brain.think

Store knowledge with full integration: entity extraction, relationship extraction, supersession processing, expertise profiling, and contradiction detection. This is the primary write path for agents.

content        string, required   The knowledge to integrate
planet         string, optional   Target planet (auto-routed if omitted)
biome          string, optional   Target biome (created if new)
cognitive_mode string, optional   Region (default: "contextual")
confidence     float, optional    0.0–1.0 (default: 0.7)
reasoning      string, optional   Why this knowledge exists
supersedes     string[], optional IDs of records this replaces
scope          string, optional   BIOME | PLANET | GALAXY (default: BIOME)
context_tags   string[], optional
agent_name     string, optional   For expertise tracking

brain.think vs memory.write: brain.think runs the full 8-step integration pipeline (entity extraction, graph linking, expertise update, contradiction check). memory.write does basic storage with entity extraction but skips expertise tracking and supersession processing. Use brain.think for decisions, learnings, and anything the agent should build expertise around.

Example — recording a decision:

{
  "content": "Switched from JWT to session tokens. JWTs can't be revoked without a blocklist.",
  "cognitive_mode": "analytical",
  "confidence": 0.9,
  "reasoning": "Blocklist defeats the stateless benefit. Session tokens with Redis give instant revocation.",
  "supersedes": ["sd-old-jwt-decision"]
}

Response:

{
  "stardust_id": "sd-abc123",
  "entities_extracted": ["JWT", "Redis"],
  "contradictions_detected": 1
}

brain.recall

Graph-enhanced retrieval. Weights by cognitive context, expands through the knowledge graph, and optionally returns reasoning chains.

query               string, required
cognitive_mode       string, optional   Bias toward a region
planet               string, optional
biome                string, optional
context_window       string, optional   Prepended to query for better matching
include_reasoning    bool, optional     Include stored reasoning (default: false)
include_graph_paths  bool, optional     Include graph context (default: false)
limit                int, optional      Default: 5

brain.recall vs memory.search: brain.recall uses cognitive mode to tune RRF weights and can expand results through graph traversal. memory.search is a simpler semantic search. Use brain.recall when you want the best possible retrieval; use memory.search for quick lookups.

brain.calibrate

Call at the end of every session. Teaches the brain what was useful. This is the feedback loop that makes retrieval improve over time.

session_id                string, required    From brain.orient
records_used              string[], required  IDs of helpful records
records_retrieved_unused  string[], optional  IDs retrieved but not used
knowledge_gaps            string[], optional  Topics where knowledge was missing
session_outcome           string, optional    Free-text summary
knowledge_quality_score   float, optional     0.0–1.0 overall rating

Effects: used records get +0.02 confidence, unused get −0.005, gaps are logged for brain.health recommendations, agent's quality score is EMA-updated.

brain.health

Cognitive health assessment for an agent. Returns overall health, knowledge freshness, coverage gaps, stale beliefs, expertise summary, and recommended enrichment actions.

agent_name  string, required

brain.know

Synthesized understanding of a concept with its graph neighborhood. Use when you want a summary of everything the Galaxy knows about a topic.

concept  string, required
depth    string, optional   "summary" | "detailed" | "full_history" (default: "summary")

brain.graph_query

Direct graph traversal from an entity. Use for exploring what connects to what.

entity_name         string, required
relationship_types  string[], optional   Filter: USES, DEPENDS_ON, REPLACES, etc.
depth               int, optional        Traversal depth (default: 2)

brain.find_path

Shortest path between two concepts (BFS, max 6 hops, cached 1 hour). Use to discover how two seemingly unrelated concepts connect.

source_concept  string, required
target_concept  string, required

brain.ask

Natural language questions routed to the appropriate operation (zero-LLM, keyword-based):

Question type	Routed to
"Who knows about X?"	Expertise lookup
"What decisions about X?"	Decision filter
"How does X relate to Y?"	Path finding
"Everything about X"	Neighborhood traversal
"Summarize X"	Synthesis