Module mcp 

MCP (Model Context Protocol) server for ai-memory. Exposes memory operations as tools for any MCP-compatible AI client over stdio JSON-RPC.

Modules

jsonrpc

JSON-RPC 2.0 wire-layer constants (#1558 batch 3).

param_names

server_identity

Daemon-side Ed25519-signed serverInfo block published in the MCP initialize handshake response.

share

MCP memory_share handler — minimal v0.8-pulled-forward implementation for issues #224 (Phase 3 Memory Sharing & Sync RFC) and #311 (targeted point-to-point memory share).

tools

v0.7.0 WT-1-C — test-only re-export bundle for the memory_atomise MCP handler. Mirrors [dispatch_handle_link_for_test]’s rationale: the integration suite at tests/wt1c_mcp_atomise.rs drives the handler directly without spinning up the stdio loop, so the handler symbol and the handler bundle struct need a stable ai_memory::mcp::tools:: path. The production wire path remains the JSON-RPC dispatch in handle_request.

Structs

IngestMultistepHandler

Handler bundle. Keeps the dispatch implementation behind an Arc<dyn LlmDispatch> so the daemon-runtime side can construct it once at MCP boot and re-use across calls. The dispatch is None until the daemon wires an LLM client (semantic-tier and below); the tier gate in handle_ingest_multistep short-circuits before consulting the dispatch in that case.

MemoryCaptureTurnRequest

memory_capture_turn request body per RFC-0001 §“Tool input schema”.

Enums

CapabilitiesAccept

Capabilities schema selector (v0.6.3.1 P1 honesty patch; extended through v0.7.0 A1–A5).

Constants

DEFAULT_EMBED_BACKFILL_BATCH_SIZE

v0.7.0 Wave-2 A5 (issue #853) — default batch size for the boot embedding-backfill loop. Tuned to balance two effects:

MCP_MAX_DRAIN_BYTES

#1249 — hard ceiling on the post-overrun drain so a peer that streams a never-ending sequence of non-newline bytes cannot keep the daemon’s drain loop spinning forever. When this ceiling fires the daemon emits a final -32700 and exits cleanly so an operator process supervisor can restart it.

MCP_MAX_LINE_BYTES

Run the MCP server over stdio. Blocks until stdin closes. Initializes components based on the requested feature tier.

Functions

build_agent_permitted_families

v0.7.0 A4 — compute the optional agent_permitted_families field for a v3 capabilities response.

build_capabilities_describe_to_user

v0.7.0 A2 — build the capabilities-v3 to_describe_to_user string.

build_capabilities_summary

v0.7.0 A1 — build the capabilities-v3 summary string from the live Profile state.

build_capabilities_tools

v0.7.0 A3 — build the per-tool array carried in the capabilities-v3 tools field.

decorate_memory_many

FX-4 / PERF-2 (2026-05-26) — batched front-end for [decorate_memory] used by the HTTP recall handler. Resolves the verbose-decoration link-attestation lookup for every memory in one SQL round-trip via [latest_link_attest_level_many] instead of N round-trips. Returns one Value per (mem, score) in input order so the caller can splice it straight into the response payload.

effective_tier_label

Round-2 F13 — derive the runtime-effective tier label from the presence of the LLM, embedder, and reranker handles. Mirrors the boot banner string emitted by serve_mcp so the memory_capabilities response and the daemon log agree on what the daemon is actually doing — independent of tier_config.tier, which only reflects the configured (build-time) tier and can lag the runtime when an embedder/LLM fails to load.

format_rule_summary

v0.7.0 K5 — format a single [GovernancePolicy] as a one-line human-readable summary, prefixed with the namespace it governs.

handle_calibrate_confidence

Wire shape:

handle_capabilities_family

v0.6.4-006 — Handle memory_capabilities invocations that pass a family=<name> parameter. When include_schema=false (default), returns the canonical tool-name list. When include_schema=true, returns the full MCP-style tool definitions for each tool — the caller (an NHI agent or a host like Claude Code’s deferred-tools path) can register them at runtime without restarting the server.

handle_capabilities_with_conn

v0.6.3 (capabilities schema v2 / P1 honesty patch): the canonical capabilities entry point.

handle_capabilities_with_conn_v3

v0.7.0 A1 — the v3-shaped capabilities entry point.

handle_capture_turn

Handler entrypoint dispatched from crate::mcp::handle_request.

handle_check_agent_action

Handler for memory_check_agent_action. Expects arguments:

handle_check_duplicate

handle_dependents_of_invalidated

MCP memory_dependents_of_invalidated handler.

handle_entity_get_by_alias

handle_entity_register

handle_expand_query

handle_export_reflection

Wire shape:

handle_find_paths

v0.7 J7 — memory_find_paths handler. Enumerates up to max_results paths through the KG between two memories using BFS with cycle detection. Backend dispatch lives in the SAL — the SQLite path goes through db::find_paths (recursive CTE); a Postgres deployment would route through PostgresStore::find_paths which dispatches on the resolved [crate::store::KgBackend] (Cypher when AGE is installed, recursive CTE otherwise). The wire shape is identical across backends: paths is a list of id chains where each chain has source_id first and target_id last.

handle_inbox

handle_ingest_multistep

Handle a memory_ingest_multistep MCP tool call.

handle_kg_invalidate

SEC-2 / COV-8 (Cluster D, issue #767) — pub so the integration test fleet can drive the handler directly. The function is still only registered as the MCP memory_kg_invalidate tool; visibility is the only thing that changed.

handle_kg_query

handle_kg_timeline

handle_list_subscriptions

handle_load_family

v0.7 B1 — memory_load_family(family, namespace?, k?).

handle_namespace_get_standard

handle_namespace_set_standard

handle_notify

handle_pending_approve

handle_pending_reject

handle_quota_status

v0.7 K8 — MCP handler for memory_quota_status. Reports per-agent quota usage (memories/day, storage bytes, links/day) for the operator-facing surface.

handle_recall

#967 — JSON-bag entry kept as a thin wrapper around [handle_recall_dto]. The pre-#967 surface continues to accept the &Value params bag so existing call sites (tests + the MCP dispatcher) compile unchanged; field extraction is delegated to RecallRequest::from_mcp_params.

handle_recall_caller

v0.7.0 #1468 — caller-scoped MCP recall entry. Identical to handle_recall but threads a visibility caller (resolved by the dispatch layer via crate::identity::resolve_read_visibility_caller) into [handle_recall_dto], which post-filters every retrieval branch by the canonical crate::visibility::is_visible_to_caller predicate. None preserves the single-tenant trust-all read posture.

handle_recall_observations

MCP handler. Filters compose with AND. Returns the ledger rows most-recent-first, JSON-shaped via observations::Observation.

handle_recall_with_pre_recall_hook

Build the standards-inheritance chain for a namespace, most-general first. Task 1.6 extends this from the historical 3-level scheme (global → parent → namespace) to N levels by walking the /-derived ancestors from crate::models::namespace_ancestors plus any namespace_meta explicit-parent chain rooted at the top of the hierarchical path (which keeps legacy flat-namespace setups working).

handle_reflect

handle_reflection_origin

MCP memory_reflection_origin handler. Returns the structured origin record for a memory id, or a clean “this memory is not a reflection” envelope when the id exists but reflection_depth == 0.

handle_replay

v0.7.0 I4 + L2-4 — memory_replay(memory_id, verbose=false, depth=null).

handle_rule_list

Handler for memory_rule_list. Accepts:

handle_skill_compositional_context

MCP memory_skill_compositional_context substrate handler.

handle_skill_export

handle_skill_get

MCP memory_skill_get substrate handler.

handle_skill_list

MCP memory_skill_list substrate handler.

handle_skill_promote_from_reflection

MCP handler for memory_skill_promote_from_reflection.

handle_skill_register

handle_skill_resource

MCP memory_skill_resource substrate handler.

handle_smart_load

v0.7 B2 — memory_smart_load(intent, namespace?, k?).

handle_subscribe

handle_subscription_dlq_list

v0.7 K7 — MCP handler for memory_subscription_dlq_list. Wraps crate::subscriptions::list_dlq and applies the optional limit cap (default 100, max 1000) so an operator inspecting a runaway DLQ can’t blow the response size budget. Family: Power.

handle_subscription_replay

v0.7 K7 — MCP handler for memory_subscription_replay. Thin wrapper around crate::subscriptions::memory_subscription_replay that exposes the operator/governance reliability tool over the MCP wire. Family: Power (operator-scoped, not data-plane).

handle_unsubscribe

handle_verify

v0.7 H4 — memory_verify MCP tool handler.

overlay_tool_payloads

Round-2 F13 — overlay per-tool inputSchema and/or docstring onto the top-level tools[] array of a v2/v3 capabilities response. Called on the no-family path when include_schema=true and/or verbose=true is set on the top-level memory_capabilities invocation. Without an overlay, those flags were inert at the top level (only the family drilldown honoured them).

persona_generate_call

Wire shape (write):

prompt_definitions

Return the list of available prompts.

run_embedding_backfill

v0.7.0 Wave-2 A5 (issue #853) — chunked boot embedding backfill.

run_embedding_backfill_with_batch_size

v0.7.0 issue #1260 — explicit-batch-size variant of run_embedding_backfill. Honors the canonical #1146 precedence ladder by accepting a pre-resolved batch size from crate::config::AppConfig::resolve_embeddings.

run_mcp_server

tool_definitions

v0.7 C2 — canonical tool catalog. Each tool entry carries a short one-sentence description (≤ 50 cl100k_base tokens) and a long-form docs field with the full prose + examples. The always-on tools/list payload strips docs via tool_definitions_for_profile; callers wanting the verbose form invoke memory_capabilities { family=<f>, verbose: true } which preserves docs so an NHI can drill in without reloading the full-fat catalog into context.

tool_definitions_for_profile

v0.6.4-002 — Filter tool_definitions() down to the tools loaded under profile. Tools whose family is not in the profile’s family list are dropped from tools[]. memory_capabilities and any other crate::profile::ALWAYS_ON_TOOLS are kept regardless of profile so the runtime-discovery dance still works on --profile core.

tool_definitions_for_profile_verbose

v0.7 C4 — full-SCHEMA-SHAPE (verbose) variant of tool_definitions_for_profile. Returns every optional param and every default (type, enum, default, minimum, maximum, required, items) — but NOT the natural-language prose: the body calls [strip_docs_from_tools], so the top-level docs field AND every per-property description string under inputSchema.properties.* are stripped here too (#1648 doc truth-fix; the pre-#1648 claim of “every per-property description” was false). Used by the memory_capabilities { verbose=true } opt-in path so power users / NHI agents can still set the long-tail knobs (confidence, priority, tier, metadata, agent_id, …) without restarting the MCP server with a different profile.

tools_check_agent_action_mutation_disabled_error

v0.7.0 (issue #691) — accessor for the stable governance.not_available_over_mcp error string. Consumed by tests/governance_immutability.rs to pin the wire vocabulary across versions. A future PR that wires the mutation refusal dispatch can re-use this constant directly rather than copy- pasting the message.