Skip to main content
Glama

nucleus

by io.github.eidetic-works

Session Management

nucleus_sessions

Session management, events, state & checkpoint tools.

Actions: save - Save session for later. params: {context, active_task?, pending_decisions?, breadcrumbs?, next_steps?} resume - Resume a saved session. params: {session_id?} list - List all saved sessions check_recent - Check for recent session to resume (alias: "current") end - End work session. params: {summary?, learnings?, mood?} start - Mandatory session start protocol archive_resolved - Archive .resolved.* backup files propose_merges - Detect redundant artifacts, generate merge proposals garbage_collect - Archive stale tasks. params: {max_age_hours?, dry_run?} emit_event - Emit event to brain ledger. params: {event_type, emitter, data, description?} read_events - Read recent events. params: {limit?} get_state - Get brain state. params: {path?} update_state - Update brain state. params: {updates} checkpoint - Save task checkpoint. params: {task_id, step?, progress_percent?, context?, artifacts?, resumable?} resume_checkpoint - Resume from checkpoint. params: {task_id} handoff_summary - Generate handoff summary. params: {task_id, summary, key_decisions?, handoff_notes?} ingest_conversations - Ingest Claude Code JSONL transcripts. params: {mode?: "incremental"|"batch"|"single", session_id?, limit?, dry_run?} search_conversations - Search ingested conversations. params: {query, limit?, session_id?, date_from?, date_to?} list_conversations - List ingested sessions. params: {limit?, offset?, sort?: "recent"|"size"|"turns"} conversation_stats - Aggregate conversation corpus statistics register - [T3.11] Register agent session envelope. params: {session_id, agent, role, provider, worktree_path?, pid?, heartbeat_interval_s?, role_credential?} (role_credential required when NUCLEUS_ROLE_CREDENTIAL=1 — see stone-1.5) heartbeat - [T3.11] Touch last_heartbeat on an envelope. params: {session_id} unregister - [T3.11] Delete a session envelope. params: {session_id} list_agents - [T3.11] List registered agent envelopes. params: {worktree_path?, role?, alive_only?} detect_splits - [T3.11] Report (worktree, role) buckets with >1 alive session. params: {worktree_path?}

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
actionYes
paramsNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavioral traits beyond annotations, such as mandatory session start protocol, environment variable requirements (NUCLEUS_ROLE_CREDENTIAL), and flags like [T3.11] for versioning. However, side effects or error conditions are not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long and dense due to listing many actions with inline parameters. Structured as a list, but could be more concise by grouping common params or using references. Some redundancy exists (e.g., 'actions:' header).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many actions, generic schema), the description covers actions and parameters adequately but lacks examples, error handling, or return value explanations. Output schema exists, reducing the need for return descriptions, but still feels incomplete for invoking correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since schema coverage is 0%, the description compensates by listing parameters for each action (e.g., 'params: {context, active_task?, ...}') with optional indicators. This adds significant meaning beyond the generic input schema, though types and constraints are missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Session management, events, state & checkpoint tools' and lists all actions with specific verbs and resources, distinguishing it from sibling tools focused on other domains like agents or audit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. While actions are listed, there is no mention of when not to use it or comparison to sibling tools like nucleus_agents or nucleus_tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All nucleus toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

B3.3/5.0
Disambiguation4/5

Tools are grouped by domain with detailed descriptions, but some overlap exists (e.g., multiple relay-related tools like nucleus_relay, nucleus_relay_subscribe, nucleus_next_message). Overall, most tools have distinct purposes, and descriptions help disambiguate.

Naming Consistency5/5

All tool names follow the 'nucleus_' prefix with a consistent noun-like second part (e.g., nucleus_agents, nucleus_audit, nucleus_delegate). Even compound names like nucleus_lane_feedback maintain the pattern, with no mixing of conventions.

Tool Count3/5

With 28 tools, the count is on the higher end but still justifiable given the broad scope of an agent operating system. The tools cover many necessary functions, though the set could be slightly trimmed for focus.

Completeness4/5

The tool surface covers most aspects of an agent OS: agents, audit, delegation, memory, features, federation, governance, infra, lanes, messaging, orchestration, plans, relay, routing, sessions, slots, sync, tasks, telemetry. Minor gaps like a dedicated config tool are absent but not critical.

Resources