manage_substrate

Tool of io.github.butterbase-ai/mcp

Manage the entire Butterbase substrate: the action ledger, the entity graph, source artifacts, institutional memory (decisions/commitments/learnings), outbox, attention rules, snapshots, and settings. Every substrate write goes through the action ledger via "propose". The ledger captures the proposer, the policy verdict, and the result; nothing is written to the substrate without an action_id you can trace. Actions — Writes (action ledger): - "propose": Propose a write. capability ∈ {upsert_entity, update_entity, patch_entity, record_decision, record_commitment, record_learning, upsert_source_artifact, merge_entities, delete_entity, bulk_revert_actions, record_principle, retire_principle, supersede_decision, send_email_draft, revert_action}. Body: { capability, payload, dangerously_skip_approval?, idempotency_key? }. When idempotency_key matches a prior action (per substrate user, no TTL), the response returns that prior action's verdict + result and includes replay: true. - "approve": Approve a previously-proposed action that is awaiting review. { action_id }. - "reject": Reject a previously-proposed action. { action_id, reason }. Actions — Ledger reads: - "list_actions": List action ledger rows. Optional: { status?, capability?, source_app_id?, source_rule_id?, limit?, before? }. - "get_action": Get one ledger row by id. { action_id }. Actions — Entity graph: - "find_entities": List/fuzzy-search entities. Optional: { type?, q?, primary_email?, limit? (max 1000), cursor? }. type ∈ person|company|fund|workspace|team|project|event|agent|self. Returns { entities, next_cursor? }. - "get_entity": Get one entity by id. { entity_id }. - (writes use "propose" with capability=upsert_entity / update_entity / patch_entity / merge_entities / delete_entity) Actions — Source artifacts (meeting transcripts, email threads, call recordings, etc.): - "list_source_artifacts": List/search. Optional: { kind?, q?, limit?, count? }. q runs FTS over title+summary+content. - "get_source_artifact": Get one artifact by id (incl. full content). { artifact_id }. - (writes use "propose" with capability=upsert_source_artifact) Actions — Institutional memory: - "search_memory": FTS across decisions, commitments, learnings, and source_artifacts. { q?, kinds?, limit? }. q is optional — omit to list recent items. kinds = comma-separated subset of {decisions,commitments,learnings,source_artifacts}. - "list_memory": Browse memory chronologically (no FTS). Filter by source_artifact_id, kinds, superseded. { kinds?, source_artifact_id?, superseded?, before?, limit? }. - (writes use "propose" with capability=record_decision / record_commitment / record_learning / record_principle / supersede_decision / retire_principle) Actions — Outbox (side-effect dispatch queue): - "list_outbox": List rows. Optional: { status?, limit? }. status ∈ pending|in_flight|succeeded|failed|dead_letter|cancelled. - "retry_outbox": Manually re-queue a failed/dead-letter row. { outbox_id }. - "cancel_outbox": Mark a not-yet-completed row as cancelled. { outbox_id }. Actions — Attention rules (cron-triggered automation): - "list_rules": List all attention rules. Optional: { enabled? }. - "get_rule": Get one rule by id. { rule_id }. - "create_rule": Create a new rule. { rule: {name, description?, trigger_cron, condition_mode, condition, action_capability, action_payload_template, enabled?, max_fires_per_day?} }. - "update_rule": Full replace by id. { rule_id, rule }. - "delete_rule": Delete by id. { rule_id }. - "enable_rule": Set enabled=true. { rule_id }. - "disable_rule": Set enabled=false. { rule_id }. - "list_rule_firings": History for one rule. { rule_id, status?, limit?, before? }. Actions — Snapshots & settings: - "snapshots": Daily aggregate snapshots. Optional: { days? }. - "get_settings": Show substrate settings (e.g. yolo_mode). - "set_yolo": Toggle YOLO mode. { yolo_mode: boolean }. Capability default policies (what happens when you "propose" each capability): record_decision → auto (reversible) record_commitment → auto (reversible) record_learning → auto (reversible) upsert_entity → auto (reversible) update_entity → auto (reversible) patch_entity → auto (reversible) upsert_source_artifact → auto (reversible) revert_action → auto (not reversible) record_principle → approval_required (not reversible) ← mutates policy layer supersede_decision → approval_required (not reversible) ← mutates policy layer retire_principle → approval_required (not reversible) ← mutates policy layer delete_entity → approval_required (not reversible) merge_entities → approval_required (not reversible) bulk_revert_actions → approval_required (not reversible) send_email_draft → approval_required (not reversible; yolo_eligible but agent proposals always gate) Note: record_decision auto-approves, but record_principle / supersede_decision / retire_principle always require human approval — they mutate the policy-enforcement layer of the substrate. Common returns: the raw substrate API JSON response. The agent has full CRUD over the substrate via this single tool — there is no other substrate tool to call.