Skip to main content
Glama

memory_reconcile_candidates

Returns clustered memory candidates, direction-layer inventory, and promotion material so an agent can judge merges, invalidations, and keeps before applying batch memory reconciliation.

Instructions

On-demand organization · coarse screening: returns episodic-layer candidate groups + the direction-layer inventory + distillation material + operating instructions.

Memory organization = an explicit on-demand in-session action (CC is not resident; there is no background organization process). This tool performs only deterministic coarse screening (zero LLM) — the OS has no independent LLM credentials, so the judgment is made by you (the in-session agent calling the tool); the tool is responsible only for candidate coarse screening and operation application ("the agent computes, the tool stores").

Returns four blocks (project_id is automatically resolved from the current context):

  • candidate_groups: valid task_memos clustered by scope_path/task, with in-cluster BM25 pairwise similarity above the threshold paired into candidate groups (including each entry's full text + id). Make an LLM fine judgment per group: KEEP (keep all) / MERGE / INVALIDATE (contradiction invalidation) / NOOP (no action).

  • direction_inventory: the full text of all valid direction-layer entries — perform a staleness check on each (a referenced feature retired / version outdated / the world changed → propose invalidate).

  • promotion_candidates: high-frequency clusters recurring across tasks — material for distilling into direction-layer entries (the promote operation; source_refs point back to the source memos).

  • operation_guide: the four operations' semantics + the three reconcile rules (keep only the high-frequency and useful / point to the authoritative source rather than restating / prefer concise rewrites) + the hint to open ultracode when the volume is large.

After judging, hand the confirmed operations to memory_reconcile_apply for batch application.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "memory_reconcile_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
thresholdNothe in-cluster BM25 similarity pairing threshold (0-1, default 0.45)
scope_pathNoorganize only that path scope's memos (empty = the whole project's valid memos)

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.11.2

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries real weight and mostly delivers: it discloses zero-LLM determinism, that no background organization exists, that the calling agent must do the judgment, and that the tool stores rather than decides. Minor gaps remain — nothing on cost/volume limits, on whether the call has any persistent side effect, or on ordering — and the line 'the tool is responsible only for candidate coarse screening and operation application' sits slightly in tension with the later instruction to hand operations to memory_reconcile_apply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead line and the block list are reasonably front-loaded, but the prose is padded — the on-demand/no-background point is restated, and phrases like 'the agent computes, the tool stores' repeat earlier framing. Bullets help, but the body is longer than the two-parameter surface warrants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool whose real complexity is the agent-side judgment protocol rather than the inputs, the definition covers the required reasoning steps (KEEP/MERGE/INVALIDATE/NOOP, staleness checks, promotion candidates) well. Since an output schema exists, the block enumeration is somewhat redundant, but the operational guidance it adds justifies its presence; what is missing is any indication of result volume or handling of very large candidate sets.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented and baseline is 3. The description still adds meaning: it explains that threshold drives BM25 pairwise pairing within clusters, that clustering keys are scope_path/task, and that project_id is resolved automatically from context, which is not visible in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('deterministic coarse screening', 'returns episodic-layer candidate groups') and enumerates the four blocks it returns. It explicitly contrasts itself with memory_reconcile_apply ('the agent computes, the tool stores' / hand off to apply), so an agent can distinguish the pair without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use: an explicit on-demand in-session action with no background process, followed by an LLM fine judgment per group and a hand-off to memory_reconcile_apply. It does not state when NOT to call it (e.g., when there is nothing to reconcile) or what to do in the high-volume case beyond a passing mention of opening ultracode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools