brain.* tools

12 cognitive tools — orientation, thinking, recall, calibration, health, graph queries, synthesis, and diff.

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

Unified retrieval interface with four modes. Choose the mode that matches your intent:

query               string, required
mode                string, optional   "semantic" | "ask" | "synthesize" | "concept" (default: "semantic")
cognitive_mode       string, optional   Bias toward a region (semantic mode only)
planet               string, optional
biome                string, optional
context_window       string, optional   Prepended to query for better semantic matching
include_reasoning    bool, optional     Include stored reasoning (default: false)
include_graph_paths  bool, optional     Include graph context (default: false)
recency_weight       float, optional    0.0–1.0 recency bias (default: 0.3)
limit                int, optional      Default: 5

Mode	Returns	Best for
semantic (default)	Raw records ranked by similarity + recency + confidence	Finding relevant knowledge chunks
ask	Cited answer backed by specific records	"What decisions were made about auth?"
synthesize	Prose narrative over a topic (one LLM pass, no citations)	Summarising a broad topic
concept	Synthesized profile of a named entity or concept	"Tell me everything about FastAPI"

brain.recall vs memory.search: brain.recall uses cognitive mode to tune RRF weights, can expand results through graph traversal, and supports ask/synthesize/concept modes. 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

Ask a natural language question and receive a cited answer drawn from Galaxy knowledge. Routes to graph traversal or semantic search based on the question's intent.

question  string, required
planet    string, optional   Scope to one Planet
depth     int, optional      Graph traversal depth (default: 2)

Use brain.recall with mode="synthesize" instead when you want a prose narrative without citations.

brain.synthesize

Get a synthesized prose narrative about a topic. Runs a single LLM pass over all relevant records and returns a coherent narrative — no citations, no record list.

topic                    string, required
planet                   string, optional
biome                    string, optional
include_open_questions   bool, optional   Default: true
include_contradictions   bool, optional   Default: true
max_tokens               int, optional    Default: 1000

Use brain.ask instead when you want a factual, cited answer.

brain.diff

Show what changed about a topic since a given date. Useful for catching up after time away from a project.

topic   string, required   Keyword or phrase to match against stardust content
since   string, required   ISO 8601 datetime (e.g. "2026-05-01" or "2026-05-01T00:00:00")
planet  string, optional   Scope the diff to one Planet

brain.graph_full

Get the complete entity knowledge graph with all edges. Use planet to scope to one domain; max_nodes caps the result to avoid token explosion on large graphs.

planet     string, optional   Scope to one Planet
max_nodes  int, optional      Default: 100