Store knowledge in the Brain for future sessions.

Args: content: The information to remember (markdown supported). title: Short descriptive title for this memory. project: Project name (use 'global' for cross-project knowledge). tags: Keywords for easier retrieval (e.g. ["python", "fastapi", "auth"]). category: One of: architecture, bugfix, config, pattern, context, reference, note.

Search the Brain semantically. Use this to find relevant memories before starting work.

Args: query: Natural language query describing what you're looking for. project: Scope search to a specific project (None = search all). limit: Maximum number of results to return. neighbors: Attach each result's strongest graph neighbours (1 hop, typed) — graph-aware recall: what's CONNECTED surfaces even if not textually similar.

Retrieve the full content of a specific memory by its ID.

Args: memory_id: The numeric ID of the memory to retrieve.

List all memories in the Brain, optionally filtered.

Args: project: Filter by project name. category: Filter by category (architecture, bugfix, config, pattern, context, reference, note).

Update an existing memory's content or tags.

Args: memory_id: The numeric ID of the memory to update. content: New content (replaces existing). Pass None to keep current content. tags: New tags (replaces existing). Pass None to keep current tags.

Permanently delete a memory from the Brain.

Args: memory_id: The numeric ID of the memory to delete.

Log a decision for future reference. Invaluable for understanding past choices.

Args: decision: What was decided. rationale: Why this choice was made. alternatives: What other options were considered and why they were rejected. context: Surrounding context that influenced the decision. project: Project this decision belongs to.

List recent decisions, optionally filtered by project.

Args: project: Filter by project name. limit: Maximum number of decisions to return.

Register a project so the Brain can auto-detect it from the working directory.

Args: name: Short project identifier (e.g. 'feynotes', 'laplacebo'). description: What this project is about. paths: Filesystem paths associated with this project (for auto-detection).

List all registered projects.

Auto-inject relevant context at the start of a session. Call this FIRST.

Detects the current project from cwd, then returns a COMPACT overview (~300-600 tokens): memory/decision pointers with ids, what needs review, stats. Drill into anything with expand_memory(ids=[...]).

Args: cwd: Current working directory (for project auto-detection). task_description: Brief description of what you're about to do (improves relevance). limit: Max memories to include. max_tokens: Token budget for the dense format — truncated by relevance, not by age. format: "dense" (default, compact markdown) or "json" (full previews, verbose).

Drill-down dal contesto compatto: il contenuto COMPLETO di una o più memorie.

Args: ids: Gli id (max 10) presi dai puntatori #id di get_context/recall.

Check Brain health and statistics.

Spreading-activation recall over the memory graph (HippoRAG-style).

Unlike recall (pure cosine top-k), this seeds the query's best matches and propagates activation along citation, semantic, and shared-entity edges, so strongly-connected memories surface even when not textually similar. Returns the associative ranking AND the plain-cosine baseline for comparison.

Args: query: Natural language query. project: Scope to a project (None = whole brain). limit: Number of results.

Show the memories most strongly linked to a given one (typed neighbours).

Args: memory_id: The memory to expand from. limit: Max neighbours to return.

Overview of the brain as a graph: hubs, orphans, components, a Mermaid diagram of the citation backbone, and (if built) the Graphify entity graph with communities, god-nodes and surprising connections.

Args: project: Scope to a project (None = whole brain). focus_id: If set, the Mermaid diagram is centred on this memory. include_entities: Include the Graphify entity-graph summary.

(Re)build the Graphify entity knowledge graph over the brain.

Runs extraction via the local claude CLI (free; uses your Claude plan). Requires graphifyy installed (pip install graphifyy). Cached under BRAIN_DIR/.constellation so other tools read it instantly.

Show prior versions of a memory (preserved on every update — non-destructive).

Args: memory_id: The memory whose edit history to retrieve.

Scan the brain for memories that have likely gone stale and need review: superseded by a newer memory, past a temporal deadline, conditional/provisional, or already flagged. Read-only — it suggests, never deletes. Confirm with flag_stale.

Args: project: Scope to a project (None = whole brain).

Update a memory's belief envelope. None args keep the current value.

Args: memory_id: The memory. confidence: 0..1 how sure we are. status: active | stale | retired. valid_until: ISO date after which the claim expires. review_reason: why the status/confidence changed. superseded_by: id of the memory that replaced this one.

Mark a memory as stale: kept and recoverable, but annotated in recall.

Args: memory_id: The memory to flag. reason: Why it's stale. superseded_by: id of the memory that replaced it, if any.

Think across memories: surface cross-project analogies and non-obvious connections that recall cannot reach (reuses the Graphify graph — no extra LLM cost). Candidates are saved as proposed insights (unless store_them=False) for you to accept_insight / reject_insight.

Args: project: Scope to a project (None = whole brain). limit: Max candidates. store_them: Persist candidates as proposed insights.

List reflection insights, optionally by status (proposed | accepted | rejected).

Accept an insight: mark it accepted and promote it to a real memory linked to its source memories.

Args: insight_id: The insight to accept. project: Project for the promoted memory.

Reject an insight (kept on record, marked rejected).

Args: insight_id: The insight to reject.

Interrogate decision provenance: WHY are things the way they are?

Ask "why do we use X and not Y?" — returns the matching decision(s) with rationale, the rejected alternatives, the context, plus the memories that cite each decision (its evidence in the graph) and what supersedes what.

Args: question: The "why" question, natural language. project: Scope to a project (None = whole brain). limit: Max decisions to explain.

Time-travel: what did the brain believe at a given date?

Memories that existed then, with their content AS IT WAS (reconstructed from the non-destructive version history), and which of them were already superseded or expired at that date.

Args: date: ISO date ("2026-03-01") — the point in time to reconstruct. query: Optional filter — only memories relevant to this (searched today, content returned as of the date). project: Scope to a project. limit: Max memories.

The brain's "sleep": walk the graph and PROPOSE housekeeping (read-only).

Like consolidation during sleep: finds dense communities whose memories are near-duplicates (→ merge candidates), leaves never recalled and fading (→ decay candidates for flag_stale), and disconnected orphans. Nothing is changed — you (or your agent) act with merge_memories / flag_stale.

Args: project: Scope to a project (None = whole brain). min_similarity: Cosine threshold for merge candidates inside a community.

Propose groups of redundant/overlapping memories to merge (READ-ONLY).

Finds clusters of highly-similar memories. Nothing is modified: review the groups, write a synthesis yourself, then call merge_memories(...) — the sources get marked superseded (never deleted, always recoverable).

Args: project: Scope to a project (None = whole brain). threshold: Cosine similarity above which two memories are considered redundant. max_groups: Max candidate groups to return.

Merge redundant memories: store the synthesis as a NEW memory and mark the sources superseded (kept and recoverable — never deleted).

Args: source_ids: The memories being consolidated (≥2). title: Title of the merged memory. content: The synthesis you wrote (the sources' provenance is appended automatically). project: Project for the merged memory. tags: Tags for the merged memory.

Find recurring-incident clusters and propose always-on rules for review. Read-only — never edits your operating instructions.

Args: project: Scope to a project (None = whole brain).