| name | memfleet-publish-intent |
| description | Always use BEFORE modifying any symbol in a multi-agent session to register structural intent and surface blast radius + active conflicts. Triggered by: about to refactor / rename / delete / modify code, planning an edit, checking if another agent is working on the same area, pre-edit coordination, leader-driven multi-symbol waves. Do not edit first and publish after — the whole point is to surface conflicts BEFORE the wasted edit. Do not pass intent_kind as a flat string; it is a typed enum with a JSON-object shape. |
Overview
Register a structural intent against a symbol BEFORE editing. Returns the precomputed blast radius (the propagation set of nodes implicated by your edit) and any conflicts already declared by other agents.
This is the first call in memfleet-safe-edit Step 2. Skipping it means you discover collisions at merge time instead of at intent time, which is exactly what MemFleet exists to prevent.
Quick Reference
| Tool | Purpose |
|---|
publish_intent | Declare intent; get blast radius + active conflicts |
get_node_state | (Optional pre-call) inspect recent activity on the symbol first |
fleet_status | (Optional pre-call) confirm the broker is up and not in a conflict storm |
Parameter types: MCP parameters are strictly typed. intent_kind MUST be a JSON object naming the variant ({"Refactor": {"pattern": "RenameSymbol"}}); a flat string like "Refactor(RenameSymbol)" is rejected. Numbers (ttl_ms) must be JSON numbers, not quoted strings.
Steps
1. Identify the target symbol
Locate the symbol you are about to edit using whatever discovery tool your harness has:
- Memtrace installed? → Use
find_symbol / find_code (they return the canonical NodeIdentity).
- No Memtrace? → Use your editor's go-to-definition or
grep for the qualified name. The symbol field is a free-form string the broker treats as the NodeIdentity.
2. Pick the IntentKind variant
Choose the variant matching your planned edit:
| Variant | Use for |
|---|
Refactor { pattern: RenameSymbol | ExtractFunction | ... } | Structural rewrites that preserve behaviour |
FeatureAdd { surface: NewSymbol | NewField | NewEndpoint | ... } | Net-new functionality |
BugFix { defect: NullHandling | RaceCondition | OffByOne | ... } | Behaviour corrections |
Cleanup { kind: DeadCode | FormatOnly | Lint | ... } | Non-semantic tidying |
Performance { axis: Latency | Memory | Throughput | ... } | Optimisations |
SecurityFix { severity, cve? } | Security patches; CVE optional |
TestAdd { covers: [NodeIdentity] } | New tests covering specific symbols |
DocsOnly | Comments, docstrings, README — no semantic change |
Exploratory | Probe / scout / kickoff signals; not a real edit |
Pass the variant as JSON, never as a flat string.
3. Call publish_intent
mcp__memfleet__publish_intent({
repo_id: "my-repo",
symbol: "UserRole",
intent_kind:{"Refactor": {"pattern": "RenameSymbol"}},
ttl_ms: 300000,
agent_id: "claude-code-session-42" // optional but recommended
})
Parameters:
repo_id — string, required. The repository the symbol lives in.symbol — string, required. The NodeIdentity (qualified name) of the target.intent_kind — JSON object, required. One of the variants above.ttl_ms — integer, required. How long the intent stays live without renewal. Default sane choice: 300_000 (5 minutes).reference_time — RFC3339 string, optional. Defaults to "now". Used for LWW arbitration on Class B.agent_id — string, optional. Helps fleet_status / get_node_state attribute the intent to a person/session.
Success criteria: the broker returns intent_id, propagation_set, and active_conflicts (possibly empty).
4. Read the response
{
"intent_id": "01H…",
"propagation_set": ["UserRoleRepo", "UserSessionService"],
"active_conflicts": []
}
| Field | Meaning |
|---|
intent_id | ULID. Save it — every subsequent record_episode references it. |
propagation_set | Nodes the broker thinks your edit will ripple into. Other agents on these nodes get a structural signal in their next get_node_state. |
active_conflicts | Empty = clear to edit. Non-empty = branch to memfleet-conflict-resolution. |
5. Decide
Decision Points
| Situation | Action |
|---|
| You are about to touch multiple symbols | Publish one intent per symbol; collect all intent_ids before editing |
| The edit is exploratory (probe, hypothesis test) | Use intent_kind: "Exploratory" so others know it is not a real edit |
| You already published earlier this session and it timed out | Publish a fresh intent; TTL has expired so the prior intent is no longer in active_intents |
propagation_set is enormous (>50 nodes) | Consider splitting the intent into narrower scopes before proceeding |
| Multi-agent wave (leader/follower) | Encode the correlation tag in the intent surface — see memfleet-fleet-coordination |
Common Mistakes
| Mistake | Reality |
|---|
| Editing first, publishing after | The whole point is to detect conflicts BEFORE the wasted edit. Reverse the order. |
Passing intent_kind as a flattened string ("Refactor(RenameSymbol)") | Rejected by the schema. Use the JSON-object form. |
Quoting ttl_ms as a string ("300000") | Rejected; must be a JSON number. |
Using a Unix epoch for reference_time | RFC3339 only. Wrong format = silent fall-through to "now". |
Setting ttl_ms to a huge value "to be safe" | Long TTLs pin the intent and starve other agents. Pick the actual edit horizon (5–15 min typical). |
Ignoring propagation_set | Those are the nodes other agents will see flagged. Sanity-check that they make sense. |
Treating an Exploratory intent as "publishing nothing" | Exploratory still creates a NodeState entry — useful for later get_node_state introspection. |
Skill Priority
This is the first MCP call in any coordinated edit. Pair with:
