CLAUDE.md / MCP tool schema mismatch: memory_retrieve does not accept 'query'

[emp3thy]

Symptom

Calling mcp__better-memory__memory_retrieve with a query argument fails:

Input validation error: Additional properties are not allowed ('query' was unexpected)

This happened twice in a single session while following the mandatory startup-retrieve instructions in CLAUDE.md.

Root cause

There is a mismatch between the documented contract and the actual tool schema.

CLAUDE.md says (the global private one + the project-level startup instructions):

At the very start of every conversation, before doing anything else, retrieve context for the current working directory / project:

• mcp__better-memory__memory_retrieve with a broad query describing the project or task area. Returns observations bucketed by outcome (do, dont, neutral).

Before doing meaningful work beyond the initial read, retrieve task-specific context:

• mcp__better-memory__memory_retrieve — narrow query + optional component (subsystem/module) and scope_path (file or directory)
• Tune window (default 30d) — use none to search everything, or 24h for very recent only

The actual MCP schema (reported by ToolSearch):

{
  "name": "mcp__better-memory__memory_retrieve",
  "description": "Retrieve reflections (do / dont / neutral lessons distilled from prior observations) bucketed by polarity. Filter by project, tech, phase, and polarity. For raw observation lookup, use memory.retrieve_observations.",
  "parameters": {
    "additionalProperties": false,
    "properties": {
      "limit_per_bucket": {"type": "integer"},
      "phase":   {"enum": ["planning", "implementation", "general"]},
      "polarity":{"enum": ["do", "dont", "neutral"]},
      "project": {"type": "string"},
      "tech":    {"type": "string"}
    }
  }
}

Three concrete divergences:

1. No query parameter — tool is filter-only. Any query argument is rejected because additionalProperties: false.
2. No component or scope_path parameters — CLAUDE.md instructs the model to pass them, but they don't exist on the schema.
3. No window parameter — CLAUDE.md instructs window=none / window=24h; not present.
4. Returns reflections, not observations — CLAUDE.md says "Returns observations bucketed by outcome." Tool description says "Retrieve reflections … bucketed by polarity." Different entity, different bucket key.

For free-text + recency filtering of raw observations, the actual tool is memory_retrieve_observations, which DOES accept query, component, theme, outcome, episode_id, etc.

Failures from this session

Both calls below were rejected:

mcp__better-memory__memory_retrieve(query="memory rating self-rating reflection scoring usefulness")
→ Input validation error: Additional properties are not allowed ('query' was unexpected)

mcp__better-memory__memory_retrieve(query="reflection synthesis pipeline scoring promotion")
→ Input validation error: Additional properties are not allowed ('query' was unexpected)

The model only succeeded after dropping query and using phase="planning", which returns a coarse bucketed reflection set unrelated to the task.

Why this matters

The startup retrieve is marked MANDATORY in CLAUDE.md ("This is non-negotiable"). The documented invocation pattern fails on every fresh session, so the model either:

• gets stuck retrying with progressively reduced parameters, or
• silently downgrades to a less-useful filter-only call,

which defeats the purpose of the rule.

Suggested fix (pick one)

1. Update CLAUDE.md (and any embedded skill snippets) to reflect the real surface:
   • Use memory_retrieve_observations(query=..., component=..., outcome=...) for free-text retrieval.
   • Use memory_retrieve(project=..., tech=..., phase=..., polarity=...) for the bucketed-reflections summary at startup.
   • Remove window from the documented parameter list, or implement it.
2. Or add query / component / window support to memory_retrieve so it matches the documented contract.

Option 1 is cheaper and matches the existing two-tool split (retrieve = distilled reflections, retrieve_observations = drill-down search).

Affected files (likely)

• ~/.claude/CLAUDE.md — global instructions
• better_memory/skills/CLAUDE.snippet.md — skill index snippet
• better_memory/skills/memory-retrieve.md — retrieve workflow