MCP-1C: Define MCP tool schemas, routing, and bounded response contracts

[Atharva-Kanherkar]

MCP-1C: Define MCP tool schemas, routing, and bounded response contracts

Summary

Lock the tool contracts before transport work starts so the MCP layer has stable, typed request/response models and bounded outputs for host clients with tool and token limits.

Scope

• typed request/response models for the MCP tool surface
• shared success/error envelope
• serializers for memory records, contradiction candidates, procedural matches, and forgetting reports
• get_memory(memory_type, record_id) routing
• explicit store-first-then-contradiction-check ordering for remember_fact
• truncation controls for large forgetting reports

Acceptance Criteria

• all tools return machine-readable structured output
• errors are stable and typed
• forgetting preview/run responses cap decisions and report truncation
• recall_procedures is explicitly backed by ProceduralStore.get_best_procedure_matches()
• recall_episodes covers recent, session, and time_range without extra recall tools

Dependencies

• Parent: MCP-1: Add an MCP server layer for agentic-memory #55
• Depends on: MCP-1B: Harden core retrieval, contradiction status, and forgetting concurrency #59
• Blocks: MCP-1D: Implement the FastMCP server and transport startup #61, MCP-1E: Add multimodal MCP input handling for local paths and inline payloads #62

[Atharva-Kanherkar]

@claude before solving this issue (please see the code that has been already implemented) and the issues (hte parent issues and the other subissues) and then tell me, are there any important learnings or decisons that still might be have to questioned before we move to a concrete solution?

[claude]

Claude finished @Atharva-Kanherkar's task in 1m 51s —— View job

---

Pre-Implementation Analysis: Open Questions for MCP-1C

• Gather context: reading codebase and related issues
• Review existing implementation (API, stores, models, forgetting service)
• Identify open questions and decisions

---

Here are the significant gaps and questions to resolve before locking down the MCP-1C schemas. I've graded each by how much it will affect downstream work (#61, #62):

---

1. Tool surface: per-type vs. unified — HIGH IMPACT

The existing REST API exposes type-specific endpoints (POST /api/memories/semantic, POST /api/memories/episodic/text, POST /api/memories/procedural). The issue names MCP-level tools like remember_fact (singular) and recall_episodes (type-specific). You need to decide: is the MCP surface a thin wrapper over REST (one tool per endpoint) or a coarser LLM-friendly surface (remember, recall, forget_preview)? These produce very different schemas, and you can't mix the two approaches without ambiguity.

---

2. get_memory(memory_type, record_id) — routing gap

No cross-store get_by_id exists today. Each store has its own get_by_id. The MCP tool must dispatch to the right store based on memory_type. This is trivial to implement, but it's a new code path not yet in api/app.py. Does this live in the MCP layer or get added to the REST API first?

---

3. remember_fact — what types does it cover?

"Fact" implies semantic. But episodic and procedural memories need to be stored too. Does the MCP layer have:

• remember_fact (semantic only) + log_episode + register_procedure, or
• One remember tool with a memory_type parameter?

The issue only explicitly names remember_fact, leaving the others ambiguous. Deciding this now prevents the transport layer (#61, #62) from making assumptions.

---

4. Forgetting report truncation — no cap exists today — MUST DECIDE

_serialise_forgetting_report in api/app.py:360–389 emits every decision with no size limit. The issue says "cap decisions and report truncation." What is the default cap (50? 100?) and what field signals truncation? Suggest:

{
  "decisions": [...up to N...],
  "decisions_truncated": true,
  "total_decisions": 843
}

This needs to be in the schema before the serialiser can be written.

---

5. recall_episodes — three modes in one tool, or three tools?

Currently the REST API has three separate endpoints:

• GET /api/episodes/recent → retriever.query_recent()
• GET /api/episodes/session/{session_id} → episodic_store.get_by_session()
• GET /api/episodes/time-range → retriever.query_time_range()

The issue says recall_episodes covers all three "without extra recall tools." So the single MCP tool needs a mode discriminator (recent | session | time_range) with conditional required params. Is that the intent? A union-type schema here is non-trivial to validate cleanly.

---

6. Contradiction response in remember_fact — inline or separate tool?

The REST API already implements store-first-then-contradiction-check and returns candidates in the same response (api/app.py:504–519). The issue confirms this ordering. But for MCP: should contradiction candidates be in the remember_fact response, or should the host be expected to call a separate check_contradictions tool? Inline is simpler; separate is more composable. This affects whether the response envelope is bounded (contradiction list could be large).

---

7. Multimodal fields in the MCP schema

The existing models support media_ref, media_type, source_mime_type. MCP tools are text-in/text-out. Options:

• Drop multimodal support from MCP tool schemas entirely (point users to REST)
• Accept media_ref as a pre-uploaded path string
• Accept base64 inline content

The issue doesn't mention multimodal at all. Leaving it unspecified means transport (#61, #62) will need to revisit the schema.

---

8. Error envelope — shared shape not yet defined

The issue says "shared success/error envelope." The REST layer uses HTTPException with varying status codes. MCP tools return results or raise errors through a different mechanism. Two questions:

• Should every tool response be wrapped in {"ok": true, "data": {...}} / {"ok": false, "error": {...}}?
• Or do MCP errors propagate via the protocol's native error channel, keeping the success body flat?

The answer changes every serialiser in scope.

---

9. recall_procedures — top_k default and score fields

ProceduralStore.get_best_procedure_matches() (procedural_store.py:172) returns ProceduralMatch with similarity, wilson_score, combined_score. The _serialise_procedural_match function in api/app.py:262 already serialises these. The only open question: should the MCP schema expose all three scores (useful for debugging) or just combined_score (cleaner for LLM consumers)?

---

10. Token budget — undefined

"Bounded outputs for host clients with tool and token limits" is in the issue summary but no max token counts are proposed. Without concrete numbers, it's impossible to decide what to truncate and when. Recommendation: define a max_decisions parameter defaulting to 50 for forgetting tools, and top_k capping at 20 for retrieval.

---

Summary

The most blocking gaps before writing concrete schemas are:

Decision	Blocks
Per-type vs. unified tool surface	All schemas
Forgetting truncation fields & default cap	forget_preview / run_forgetting schemas
Contradiction inline vs. separate tool	remember_fact schema
recall_episodes mode discriminator shape	recall_episodes schema
Error envelope shape	All schemas

The get_memory routing, recall_procedures score exposure, and multimodal exclusion are lower-risk decisions that can be resolved quickly.

[Atharva-Kanherkar]

@claude I went through all 10 open questions and here is the set of decisions I would lock for MCP-1C, with the reasoning spelled out in plain language and in real host-LLM scenarios.

1. Tool surface: per-type vs unified

My answer: use a small task-oriented MCP surface, not a 1:1 mirror of REST, and not one giant generic tool.

Recommended shape:

• remember_fact
• remember_episode
• remember_procedure
• recall_memories
• recall_episodes
• recall_procedures
• plus the admin/utility tools already proposed in MCP-1: Add an MCP server layer for agentic-memory #55

Why I think this is better:
In plain English, the host LLM should see a few clear buttons, not either:

• a huge dashboard of backend-flavored tools, or
• one overloaded button called remember(memory_type=...)

A model like Claude Code or Codex is better at choosing between a few distinct tasks than at remembering a big union schema every time.

Real-life scenario:

• User says: "The default embedding size is 768." -> Claude Code should call remember_fact.
• User says: "Yesterday we migrated the Chroma path and retrieval got flaky." -> Codex should call remember_episode.
• User says: "If contradiction candidates appear, ask the user before superseding." -> Claude Code should call remember_procedure.

That is cleaner and safer than one mega-tool.

What changes if we choose differently:

• If we mirror REST 1:1, MCP becomes too plumbing-shaped for the host.
• If we use one mega-tool, the model has more chances to put valid content into the wrong memory type.

2. get_memory(memory_type, record_id) routing gap

My answer: implement this routing in the MCP/core layer now. Do not block on adding a REST-first endpoint.

Why I think this is better:
This is basically receptionist logic. The caller already knows the memory type, so MCP can route directly to the right store.

Real-life scenario:
Codex stores a procedural memory, gets back the record ID, and later wants to fetch that exact memory again. It already knows that the record is procedural, so get_memory(memory_type="procedural", record_id="...") is enough.

What changes if we choose differently:
If we insist on adding a new REST endpoint first, MCP-1C and MCP-1D become unnecessarily dependent on API surface changes that do not add much value.

3. remember_fact: what types does it cover?

My answer: remember_fact should be semantic only. Episodic and procedural should each have their own write tools.

Why I think this is better:
The name already answers the question. A fact is not an episode, and it is not a procedure.

If we make remember_fact secretly flexible, the name becomes misleading and the tool docs become less trustworthy.

Real-life scenario:

• "The project uses ChromaDB" -> fact
• "In this session the user was frustrated about schema churn" -> episode
• "When retrieval quality drops, first inspect superseded semantic records" -> procedure

Those are different memory classes and the tool surface should reinforce that distinction.

What changes if we choose differently:
A generic remember tool would make examples, prompt docs, and tool selection fuzzier. It would also increase the odds that the host stores the right information in the wrong store.

4. Forgetting report truncation

My answer: make truncation explicit and conservative.

Recommended contract:

• default max_decisions = 50
• hard cap 100
• response fields: decisions, displayed_decisions, total_decisions, decisions_truncated

Example:

{
  "decisions": [...],
  "displayed_decisions": 50,
  "total_decisions": 843,
  "decisions_truncated": true
}

Why I think this is better:
The host needs enough detail to understand what happened, but not hundreds of low-level rows that eat the context window.

Real-life scenario:
Claude Code runs preview_forgetting_cycle on a large memory store. If it gets 843 individual decisions back, the tool technically succeeded but practically harmed the conversation. The host needs a bounded preview, plus totals.

What changes if we choose differently:

• No cap means unstable tool output and token blowups.
• A very large default cap encourages misuse.
• If full audits are needed later, that should be a separate report/export path, not the default MCP response.

5. recall_episodes: one tool or three tools?

My answer: one tool, with a mode discriminator:

• recent
• session
• time_range

Why I think this is better:
The parent issue already points in this direction. It keeps the tool surface smaller while still expressing the three episode lookup styles clearly.

Real-life scenario:
Claude Code may want:

• the latest recent events -> mode="recent"
• all memories from one session -> mode="session"
• everything between two timestamps -> mode="time_range"

That is still one conceptual task: recall episodes.

What changes if we choose differently:
Three separate tools would make selection noisier for the host. The downside of one tool is a more complex schema, but that is manageable with a tagged union and is worth it.

6. Contradiction response in remember_fact: inline or separate tool?

My answer: keep contradiction candidates inline in the remember_fact response, while bounding them.

Recommended contract:

• contradiction check runs after successful store
• default max_contradictions = 5
• include total_contradictions and contradictions_truncated

Why I think this is better:
The host usually wants to know immediately whether the new fact may conflict with something already stored.

Real-life scenario:
Codex stores "embedding size default is 1536" and the system finds an older semantic memory saying 768. The next best action is often immediate: ask the user which one is current, or invoke contradiction resolution. Inline results support that flow in one round trip.

What changes if we choose differently:
A separate check_contradictions tool is more modular, but it forces extra orchestration. I would only add that later if deeper contradiction workflows become necessary.

7. Multimodal fields in the MCP schema

My answer: do not defer multimodal shape design. Define it now so #62 builds on stable contracts.

Recommended input shape for relevant tools:

• file_path for local-accessible files
• inline_base64 as fallback
• return metadata and durable refs, not raw binary outputs

Why I think this is better:
If MCP-1C ignores multimodal now, MCP-1E will have to reopen the schema and churn the contract almost immediately.

Real-life scenario:

• Claude Code runs on the same machine as the MCP server and wants to store a screenshot -> file_path is ideal.
• A remote client wants to send an image that only exists on the caller machine -> inline_base64 is the fallback.

The server must validate what it can actually read on its own filesystem.

What changes if we choose differently:

• Dropping multimodal for now simplifies v1 a bit, but creates near-term schema churn.
• Supporting only base64 makes common local setups clumsy.
• Supporting only file paths breaks remote/non-local cases.

8. Error envelope: wrapped success/error vs MCP-native errors

My answer: keep success responses flat, and use the MCP/native error channel for true failures, with a stable typed payload such as:

• code
• message
• retryable
• details

For partial or non-fatal substeps, keep status inside the success payload.

Why I think this is better:
If a tool succeeds, the host should get the result directly. If it fails, the host should get a proper error. Wrapping every success in ok/data is uniform on paper, but noisy in practice.

Real-life scenario:
remember_fact stores the fact successfully, but contradiction lookup errors. That is not a full tool failure, because the store operation succeeded. So the success payload should include contradiction_check.status = "error". But if the store itself fails, that should be a real MCP error.

What changes if we choose differently:
If everything is wrapped in ok/data/error, each tool gets more verbose and we partly duplicate what MCP already provides. I would interpret "shared success/error envelope" here as "shared typed models and shared typed errors," not necessarily "wrap every success body."

9. recall_procedures: what scores should be exposed?

My answer: expose all three:

• similarity
• wilson_score
• combined_score

and document that ranking is driven by combined_score.

Why I think this is better:
The extra fields are cheap to return, and they explain why one procedure beat another.

Real-life scenario:
Claude Code asks for procedures relevant to "debug failing retrieval." One procedure may be textually very similar, but another may have a much better success history. Showing all three scores makes the ranking interpretable rather than magical.

What changes if we choose differently:
Returning only combined_score is cleaner, but it hides useful debugging context. I would only reduce the fields later if token pressure proves to be a real problem.

10. Token budget and default bounds

My answer: make the defaults and caps part of the schema contract, not an implementation detail.

Recommended defaults/caps:

• retrieval top_k: default 5, max 20
• recent episodes: default 5, max 50
• forgetting max_decisions: default 50, max 100
• contradiction candidates: default 5, max 10

Why I think this is better:
MCP outputs are not ordinary backend responses. They feed another model with a limited context window. Good limits protect the host from accidental overload.

Real-life scenario:
If Codex asks for 100 procedures, 200 recent episodes, and a full forgetting log in one conversation, the backend may survive, but the host’s reasoning quality probably gets worse because the tool output becomes too large.

What changes if we choose differently:
If these caps remain undefined, different tools will invent different limits later and MCP-1C will not really have locked the contract.

Final set of decisions I would lock now

1. Use a small task-oriented MCP tool surface.
2. get_memory(memory_type, record_id) routes in MCP/core now.
3. remember_fact is semantic-only.
4. Forgetting responses are explicitly truncated and report truncation.
5. recall_episodes is one tool with mode.
6. Contradiction candidates stay inline in remember_fact, but bounded.
7. Multimodal input shape is defined now with file_path plus inline_base64 fallback.
8. Success bodies stay flat; true failures use MCP-native typed errors.
9. recall_procedures exposes all three scores, with combined_score as the ranking field.
10. Output bounds are part of the schema, not left implicit.

One wording refinement I would make to this issue

I would slightly refine "shared success/error envelope" to mean:

• shared typed success models per tool
• shared typed error payload for real MCP failures
• shared status sub-objects for partial/non-fatal substeps

That fits MCP better than forcing every successful result into an ok/data wrapper.

If we lock the above, #61 and #62 can move forward against a stable contract without having to reopen the shape of the tool surface.

[claude]

Claude finished @Atharva-Kanherkar's task in 1m 37s —— View job

---

Decision Validation: MCP-1C Locked Contracts

• Review all 10 decisions against current codebase
• Identify any remaining nuances or gaps
• Confirm contract readiness for MCP-1D: Implement the FastMCP server and transport startup #61/MCP-1E: Add multimodal MCP input handling for local paths and inline payloads #62

---

All 10 decisions are sound and consistent with the existing codebase. Here is my validation of each, with any small refinements worth locking before implementation begins.

---

Decision 1 — Task-oriented tool surface ✅

Agreed. One note: the tool surface lists recall_memories without discussing it. Based on the REST API, this would be a semantic similarity search (wrapping retriever.query()). Confirm: recall_memories = semantic recall only, backed by RankedResult records, not a multi-type fan-out? The write-side is cleanly type-separated, so the read-side should be too (i.e. recall_facts could be the symmetric name, or keep recall_memories if it's intentionally broader). Lock the semantic scope explicitly so #61 doesn't guess.

---

Decision 2 — get_memory routes in MCP/core ✅

Agreed. The routing logic is trivial given the three stores are already wired up in MemoryAPIService. One detail: if memory_type is valid but the record_id doesn't exist in that store, the MCP error should use a stable code like NOT_FOUND rather than a raw store exception. Lock this as part of the typed error set.

---

Decision 3 — remember_fact is semantic-only ✅

Agreed. The existing REST implementation at api/app.py:491–519 already models this correctly. The store-first-then-contradiction-check ordering is already correct.

---

Decision 4 — Forgetting truncation ✅ (minor simplification)

The existing _serialise_forgetting_report at api/app.py:360–388 emits every decision with no cap. The proposed contract adds displayed_decisions, total_decisions, decisions_truncated.

One small refinement: displayed_decisions will always equal len(decisions). The host can derive it. Suggest dropping it and keeping only:

{
  "decisions": [...up to max_decisions...],
  "total_decisions": 843,
  "decisions_truncated": true
}

Saves one redundant field. If you want to keep displayed_decisions for explicit clarity, that is fine — just document it as a convenience field.

---

Decision 5 — recall_episodes with mode discriminator ✅

Agreed. One thing to lock explicitly: the conditional required parameters per mode.

mode	required extras
recent	limit (default 5, max 50)
session	session_id
time_range	start_iso, end_iso

These are already backed by retriever.query_recent(), episodic_store.get_by_session(), and retriever.query_time_range() respectively. Lock these param names now so #61 doesn't invent its own.

---

Decision 6 — Contradiction candidates inline ✅

The existing code at api/app.py:504–519 already does this correctly with _safe_contradiction_lookup. The ContradictionCheckResult at line 330–334 already carries status, candidates, and detail. The only addition needed is the truncation envelope: total_contradictions and contradictions_truncated.

The contradiction_check.status = "error" pattern for partial failures is already implemented and correct.

---

Decision 7 — Multimodal: file_path + inline_base64 ✅ (one guard to add)

The existing MediaStore already handles byte storage. The one thing to lock: a max file size for inline_base64. Large base64 payloads are a token budget hazard independent of the MCP output. Recommend capping at 10 MB on the input side (validated before decode). Without this, #62 may inherit an unbounded input path.

---

Decision 8 — Flat success bodies, typed MCP-native errors ✅

Agreed. The shared error payload shape (code, message, retryable, details) should be defined in one place so all tools reference the same model. Suggest a stable set of code values to lock now:

code	meaning
NOT_FOUND	record or resource doesn't exist
INVALID_INPUT	validation failure
STORE_ERROR	write/read failure at the storage layer
EMBEDDING_ERROR	embedding provider failure
MEDIA_ERROR	file/media operation failure

This prevents each transport (#61, #62) from inventing its own error codes.

---

Decision 9 — All three procedure scores exposed ✅

Already serialised correctly at api/app.py:262–268. No change needed. Document combined_score as the ranking field in the schema.

---

Decision 10 — Output bounds in the schema ✅

The top_k default/max and forgetting caps align with what the stores support. One note: ProceduralStore.get_best_procedure_matches() at procedural_store.py:172 defaults to top_k=3, but the MCP contract proposes default=5. Pick one and align the MCP default to match or override it explicitly. Small but worth locking.

---

Remaining gap: recall_memories scope

This is the only item in the tool surface list not explicitly addressed by the 10 decisions. Please confirm:

• Is recall_memories a semantic-only recall (backed by RankedResult)? or
• Is it a cross-type search that fans out to all three stores?

The first option is simpler and consistent with the type-separated write surface. The second would be a new code path.

---

Summary: All decisions are locked ✅

With the minor refinements above (drop displayed_decisions, add recall_memories scope, lock conditional recall_episodes params, add inline_base64 size cap, define the error code set), MCP-1C has a stable enough contract to start implementation. #61 and #62 can build against this without reopening the tool shape.

The overall design is well-reasoned and internally consistent. The multimodal-now decision (7) is the right call to avoid schema churn from #62 onwards.

---