MCP Tool: reflect

Reflect raw notes into reviewable durable memory candidates. Use reflect after planning, ideation, debugging, or building sessions to extract structured memory from unstructured notes.

Overview

Where remember captures a single piece of memory you already know you want to keep, reflect takes a block of raw session notes and extracts multiple memory candidates from it: decisions, plans, ideas, claims, artifacts, procedures, and session checkpoints. Each candidate carries a confidence score and a reason.

By default reflect only extracts and returns candidates. Use the persistence flags to write them back into Sibyl.

Input Schema

interface ReflectInput {
  // Required
  content: string; // Raw session notes to reflect on

  // Source
  source_title?: string; // Title for the reflection source (default "Session reflection")
  intent?: ContextIntent; // Goal mode (default "general")
  domain?: string; // Domain/category
  project?: string; // Project ID (sets project memory scope)

  // Linking
  related_to?: string[]; // Entity IDs to link
  task_ids?: string[]; // Task IDs for exact task context
  active_task?: boolean; // Link persisted output to the active doing task (default true)
  cited_ids?: string[]; // Context/search IDs that materially informed the reflection

  // Persistence
  persist?: boolean; // Write candidates back into Sibyl (default false)
  persist_source?: boolean; // Persist the raw reflection source (default true)
  persist_review?: boolean; // Store candidates in the raw review queue (default false)

  // Limits
  limit?: number; // Max candidates to extract (default 12)
}

Intent Values

build, plan, ideate, research, debug, decide, learn, general

Intent guides which kinds of candidates the extractor emphasizes. Note that review is accepted by the REST endpoint and the CLI but is not an MCP intent; the MCP tool rejects it.

Persistence Modes

The persistence flags control what happens to the extracted candidates:

persist	persist_review	Outcome
false	any	Extract and return candidates only, no writes
true	false	Promote candidates into the knowledge graph
true	true	Store candidates in the raw review queue for later review

persist_source (default true) controls whether the raw reflection source itself is stored as a provenance record. The review queue feeds the reflection dream-cycle, where candidates are reviewed and promoted automatically or by an operator.

Active Task Linking

With persist=true and a project, and active_task=true (default), reflect links persisted output to the single task in doing status for that project when exactly one exists. Supply task_ids for explicit linkage.

Response Schema

interface ReflectResponse {
  source_title: string;
  source_id: string | null; // Raw reflection source ID (when persisted)
  intent: string;
  domain: string | null;
  project: string | null;
  candidates: ReflectionCandidate[];
  total_candidates: number;
  persisted_count: number; // Candidates written back (0 unless persist=true)
  usage_hint: string;
  markdown: string; // Rendered Markdown view of the reflection
}

interface ReflectionCandidate {
  kind: string; // decision, plan, idea, claim, artifact, procedure, session
  title: string;
  content: string;
  reason: string; // Why this candidate was extracted
  confidence: number; // 0-1
  tags: string[];
  metadata: Record<string, any>;
  raw_source_ids: string[];
  suggested_memory_scope: string | null;
  suggested_scope_key: string | null;
  review_state: string; // pending, promoted, ...
  persisted_id: string | null; // Set when the candidate was written back
  claim_records: ClaimRecord[];
  reflection_findings: ReflectionFinding[];
  relationship_records: ReflectionRelationshipRecord[];
  sensitivity_flags: string[];
}

Usage Examples

Extract Candidates Without Persisting

{
  "name": "reflect",
  "arguments": {
    "content": "Spent the session debugging the crawler. Found that imports stall when the source has more than 5000 documents. Decided to add resumable jobs. Also noticed the adapter contract should expose a progress callback.",
    "source_title": "Crawler debugging session",
    "intent": "debug",
    "project": "proj_abc123"
  }
}

The response returns candidates (a decision, a claim, an idea) with confidence scores. No writes occur.

Reflect and Promote into the Graph

{
  "name": "reflect",
  "arguments": {
    "content": "Session notes: settled on Surreal-native storage, dropped the Postgres sidecar.",
    "source_title": "Storage architecture session",
    "intent": "decide",
    "project": "proj_abc123",
    "persist": true
  }
}

persisted_count reflects how many candidates were written into the knowledge graph.

Reflect into the Review Queue

{
  "name": "reflect",
  "arguments": {
    "content": "Rough ideas from the planning call, not all confirmed yet.",
    "source_title": "Planning call notes",
    "intent": "plan",
    "project": "proj_abc123",
    "persist": true,
    "persist_review": true
  }
}

Candidates land in the raw review queue instead of being promoted directly. They are later reviewed through the reflection dream-cycle.

Notes

• reflect without persist is read-only and safe to call freely.
• When persist=true and the credential is project-scoped, a project is required.
• Every call is authorized against the memory policy and audited.
• The markdown field is a rendered view of the reflection, convenient for prompt injection.

Error Handling

Error	Cause	Resolution
Organization context required	No org-scoped token	Authenticate with an org-scoped token
Project is required when MCP credentials are project-scoped	Project-scoped key, persist=true, no project	Supply a project
api_key_memory_space_denied	API key lacks the target memory scope	Grant the key the required memory scope

Related

• mcp-remember.md - Capture a single durable memory directly
• mcp-context.md - Retrieve durable memory for a goal
• rest-memory.md - REST reflection endpoints (/api/context/reflect)