gwt-context

MCP Tool Contracts

These contracts describe the stable response shapes that MCP clients should expect. Fields may gain additive metadata, but existing keys should not be removed without updating tests and changelog.

Tools

• gwt_store(content, memory_type="semantic", tags?, link_to?)
  • Success keys: id, memory_type, activation_state, linked_to, tags, status
  • Error keys: error
• gwt_set_goal(description, keywords?, priority=1.0)
  • Success keys: goal_id, description, priority, status
• gwt_broadcast()
  • Returns workspace broadcast text.
• gwt_compete(n_slots?)
  • Success keys: winners, would_evict, all_scores, reason, reason_breakdown
• gwt_query(query, k=5, memory_type?, admit=false)
  • Success item keys: id, content, memory_type, activation_state, activation_level, linked_ids, tags, admitted
  • Error keys: error, optional supported_memory_types
• gwt_attend(question, keywords?, k=5, passes=1, planner="auto", admit=true)
  • Success keys: question, planner, supported_planners, context_count, passes_requested, passes_completed, admit, evidence_plan, tool_call_count, admitted_ids, broadcast, workspace, trace
  • Error keys: error, optional supported_planners
• gwt_resolve(question, planner="auto", k=50)
  • Success keys: question, planner, context_count, evidence_plan
  • Error keys: error, optional supported_planners
• gwt_collection_query(operation, field?, value?, metric?, k=5, group_field?, group_a?, group_b?)
  • Success keys: operation, answer, matched_count, matched_records, supporting_evidence, metadata
  • Supported operations: count, filter, top_k, average, sum, distinct, min, max, compare
  • Error keys: error, optional supported_operations
• gwt_trace_explain()
  • Success keys: status, question, planner, strategy, answer, pass_count, tool_call_count, phases, broadcast_bus, explanation, trace
  • Empty keys: status, message
• gwt_bus_inspect()
  • Success keys: status, broadcast_bus, summary
  • summary includes proposal, accepted, inhibited, and subscriber status counts from the latest cycle-level bus read model, plus inhibited reason counts and proposal grouping data when a bus result exists.
• gwt_memory_profile()
  • Success keys: status, namespace, data_dir, embedding, persisted_item_count, runtime_index_count, structured_record_count, structured_fields, counts_by_type, counts_by_source, file_sizes, restored_runtime_items, cycle_stats, retention_policy
• gwt_readiness_check()
  • Success keys: status, checks, namespace, embedding, counts, broadcast_bus, file_sizes, restored_runtime_items
• gwt_backup_memory(memory_type?, tag?)
  • Success keys: status, format, namespace, file_sizes, item_count, jsonl
  • Format is gwt-memory-backup-v1; backup payload is JSONL plus namespace metadata, not a binary archive.
• gwt_export_memory(memory_type?, tag?)
  • Success keys: status, format, item_count, filters, jsonl
  • Format is gwt-memory-jsonl-v1; embeddings are intentionally omitted and rebuilt during import.
  • Error keys: error, optional supported_memory_types
• gwt_import_memory(jsonl, default_memory_type="semantic", tags?, admit=false, dedupe=true)
  • Success keys: status, imported_count, imported_ids, error_count, errors, admit, dedupe, skipped_duplicate_count, skipped_duplicates
  • Imported records receive active namespace tags and are re-embedded into the current namespace.
  • Error keys: error, optional supported_memory_types
• gwt_restore_memory(jsonl, mode="merge", confirm="", admit=false)
  • Supported modes: merge, replace.
  • Replace mode requires confirm="RESTORE_REPLACE", deletes existing persisted memory through IngestionPort, returns a JSONL backup, then imports the supplied JSONL.
• gwt_compact_working_memory(max_items=20, dry_run=true, confirm="")
  • Dry-run keys: status, max_items, keep_count, compact_count, candidate_ids, backup
  • Confirmed compaction requires confirm="COMPACT_WORKING", creates one semantic summary item, deletes compacted working records through IngestionPort, and returns the JSONL backup.
• gwt_reset(scope="runtime", confirm="")
  • Supported scopes: runtime, workspace, persistent.
  • Runtime reset requires confirm="RESET_RUNTIME" and clears only in-process structured read models.
  • Workspace reset requires confirm="RESET_WORKSPACE" and evicts current workspace items through CyclePort.
  • Persistent reset requires confirm="RESET_PERSISTENT", deletes memory items through IngestionPort, clears the runtime read model, and returns a JSONL backup in the response.
• gwt_evict(item_id)
  • Delegates to CyclePort.evict_workspace_item; payload is cycle-defined.
• gwt_link(source_id, target_id)
  • Delegates to CyclePort.link_items; payload is cycle-defined.
• gwt_inspect(target="workspace")
  • Delegates to CyclePort.inspect; payload is target-specific read model.
  • target="broadcast_bus" returns whether the cycle bus is configured, the configured subscriber names, bus settings/budgets, latest bus result, summary, proposal groups, and linked-memory reactivations from the latest cycle.

Broadcast Bus Result Shape

Serialized bus results include proposals, accepted, inhibited, decisions, summary, proposal_groups, and subscriber_reports.

decisions records one arbitration outcome per accepted or inhibited proposal:

{
  "status": "accepted",
  "reason": "accepted",
  "proposal": {}
}

Current inhibition reason codes are below_threshold, duplicate_key, max_accepted, and resolved_answer_present.

Evidence Plan Shape

Tools that return evidence_plan use:

{
  "strategy": "string",
  "answer": "string",
  "queries": ["string"],
  "evidence": ["string"],
  "metadata": {}
}

Planner names are auto, generic, semantic, structured, graph, and hybrid.