This page summarizes the current public mubit.v1.ControlService RPC surface. Use it for generated-client debugging and transport-parity checks.
Service identity
- Package:
mubit.v1
- Service:
ControlService
Core memory RPCs
| Group | RPCs |
|---|
| Ingestion | Ingest, BatchInsert, GetIngestJob, GetRunIngestStats, ArchiveBlock, Dereference |
| Retrieval and context | Query, GetContext, ListActivity, ExportActivity, GetRunSnapshot |
| Diagnostics and reflection | Diagnose, Reflect, ListLessons, DeleteLesson, GetMemoryHealth |
MAS and learning-loop RPCs
| Group | RPCs |
|---|
| Agent identity | RegisterAgent, ListAgents, AgentHeartbeat, AppendActivity |
| Compaction and reinforcement | Checkpoint, RecordOutcome, RecordStepOutcome, SurfaceStrategies |
| Coordination | CreateHandoff, SubmitFeedback |
| Run management | DeleteRun, LinkRun, UnlinkRun |
Explicit planning state RPCs
| Group | RPCs |
|---|
| Goals | AddGoal, UpdateGoal, ListGoals, GetGoalTree |
| Variables | SetVariable, GetVariable, ListVariables, DeleteVariable |
| Concepts | DefineConcept, ListConcepts |
| Actions | SubmitAction, GetActionLog |
| Decision cycles | RunCycle, GetCycleHistory |
Practical parity checks
- Helper-first SDKs should map cleanly onto these RPC groups even when they expose more ergonomic names.
GetContext is the primary gRPC compaction-safe context assembly surface.ListActivity and ExportActivity are the chronological audit/browse surfaces; use them when you need exact ordering and pagination rather than ranked retrieval.Diagnose, GetMemoryHealth, Reflect, RecordOutcome, RecordStepOutcome, and SurfaceStrategies are the key loop-inspection and reinforcement RPCs.RecordStepOutcome records per-step process rewards with signal, rationale, and directive hint for dense RL within a run.Reflect accepts step_id, last_n_items, and include_step_outcomes for step-wise scoped reflection.Ingest, Query, and GetContext accept lane fields (lane, lane_filter) for multi-agent memory isolation within a shared run.ArchiveBlock and Dereference are the exact-reference pair: archive an exact artifact once, then recover it later by stable reference_id.
Evidence provenance and telemetry
Query and GetContext now expose exact-reference provenance on surfaced evidence:
retrieval_modereference_idreferenceableorigin_entry_type
GetContext also returns context-pressure telemetry:
- source counts by entry type and retrieval mode
- evidence candidates considered
- evidence dropped by token budget
- exact references surfaced
Step-level outcomes
RecordStepOutcome records a per-step process reward signal within a run, complementing the run-level RecordOutcome. Use it after each agentic step where you want dense feedback for reflection.
| Field | Type | Description |
|---|
run_id | string | Session/run identifier |
step_id | string | Unique step identifier within the run |
step_name | string | Human-readable step label (e.g. "initial_planning") |
outcome | string | One of success, failure, partial, neutral |
signal | float | Reward signal from -1.0 to 1.0 |
rationale | string | Why this outcome was assigned |
directive_hint | string | Hindsight guidance for future runs (Hindsight-Guided OPD) |
agent_id | string | Agent that performed the step |
user_id | string | Optional logical user scope |
metadata_json | string | Arbitrary JSON metadata |
step_outcome_id and accepted. Emits context.step_outcome_recorded event.
Lane-scoped memory
Lanes partition memory within a shared run so each agent sees only relevant entries.
| RPC / Field | Description |
|---|
IngestItem.lane | Tags ingested items with a named lane |
AgentQueryRequest.lane_filter | Retrieves only entries tagged with the specified lane |
ContextRequest.lane_filter | Filters context assembly by lane |
AgentRegisterRequest.shared_memory_lanes | Declares which lanes an agent participates in |
lane_filter matches or is empty.
lane (MAS memory isolation) is distinct from the core data-plane retrieval lane concept used in direct search routing.
Failure modes and troubleshooting
| Symptom | Root cause | Fix |
|---|
| gRPC behavior differs from helper behavior | You are comparing a helper to the wrong raw RPC | Check whether the helper wraps Query, GetContext, or another control RPC |
| Reflection succeeds but learning feels weak | Outcomes are not being recorded | Pair Reflect with RecordOutcome |
| Context feels incomplete | Wrong mode or budget settings | Validate ContextRequest mode, sections, and token budget fields |
| Step outcomes recorded but reflection ignores them | include_step_outcomes defaults to false | Pass include_step_outcomes=True in ReflectRequest |
| Lane-filtered query returns nothing | Lane name mismatch or items ingested without lane | Verify the lane value at ingest time matches lane_filter at query time |
Next steps
