The smart-memory-mcp package exposes SmartMemory operations as Model Context Protocol tools. Tools are defined with FastMCP's @mcp.tool() decorator and registered into one of three tiers:
FREE — registered for every session (26 tools, including the decision tools).
All tools return strings (or, for get_working_context, a structured dict). The three save tools (memory_save, memory_save_document, memory_save_conversation) return a one-line summary plus structured content: status (saved, held, queued or failed), the saved id, the save receipt and the receipt's summary. Parameter types below are taken directly from the function signatures in smart-memory-mcp/smartmemory_mcp/tools/.
Save one memory. Pass exactly one of content (free text) or data (a structured record). Free text goes through the full extraction pipeline, except memory_type="pending", which is stored as is. memory_type defaults to semantic for text. For data, memory_type names the registered schema and is required, and metadata and tags are not allowed.
Update a memory item's properties (CORE-CRUD-UPDATE-1).
memory_delete
(item_id: str)
Delete a memory item by ID.
memory_clear
(confirm: bool = False)
Clear all memories permanently — requires confirm=True.
memory_list
(limit: int = 20, offset: int = 0)
List memories with pagination.
memory_stats
()
Memory count statistics grouped by type.
memory_save_conversation
(turns: list, conversation_id: str = None, session_boundaries: list = None, session_dates: list = None, turns_per_chunk: int = 15, max_chunk_chars: int = 12000)
Save one conversation turn pair or a whole transcript. Exactly two turns (a user turn, then an assistant turn, with no boundaries or dates) are stored as one pending memory. Anything else is a transcript, grouped into sessions and run through the extraction pipeline under one conversation container (RLM-1g).
memory_search_advanced
(query: str, algorithm: str = "query_traversal", max_results: int = 15)
Similarity Graph Traversal (SSG) search.
memory_search_by_metadata
(metadata_key: str, metadata_value: str, top_k: int = 10)
Find potentially unused functions, components and hooks. A function that is called, tested or used by value (passed as a callback, stored, exported or used as a default) is not reported. Methods of a class that is itself used, exported or an entry point are not reported. A use that exists only in a TypeScript type annotation does not count. Uses from another workspace or repository never count. Candidates with unknown registration reachability are excluded. Two options are off by default. include_exported=True also reports exported functions that nothing calls (entry points, unknown reachability and members of a used class are still excluded). production_only=True counts only uses from non-test files, so a function used only by tests is reported. A test file is a file that defines at least one test. The result echoes both options under options. The two options are independent. include_exported reports exported functions with no counted caller, and test callers count unless production_only is on, so an exported function used only by tests is reported only when both options are on.
Trace what calls / imports / inherits what. A name that matches several entities returns the list of candidates.
Framework registration analysis distinguishes proven entry points, unknown reachability and unsupported registrations. Unknown candidates are excluded from dead-code results across local, remote and hosted tools. Their framework_evidence records "reachability unknown" as reachability="unknown", with the reason in basis. Dependency results expose that evidence. A receiver or callback name duplicated or written anywhere in its file cannot establish registration provenance. Type-only imports (import type) never establish it either. If a file contains any registration that cannot be proven or ruled out, every function in that file, and every function those functions call, is treated as unknown rather than dead.
MCP memory_search and memory_search_by_metadata accept since and until as
ISO-8601 strings or relative durations such as 7d, 24h, and 30m. Both bounds
resolve at one instant; all output modes echo the resolved absolute window and
creation-time coverage, including empty and citation responses. Both local and
remote backends forward the bounds.
CLI: sm search "atlas budget" --since 7d --until 24h. The flags filter storage
creation time with an inclusive lower and exclusive upper bound on both daemon
and in-process paths. sm search --help describes the accepted forms.
hop_strategy accepts consensus, relevance, or semantic on
POST /memory/search, Python SDK search(), and MCP memory_search.
JS SDK uses memory.search(query, { multiHop: true, hopStrategy: 'relevance' }).
The Python equivalent is client.search(query, multi_hop=True, hop_strategy="relevance").
consensus follows entities several top results agree on and may stop before a
one-off bridge when distractors lower its frequency score.
relevance follows entities from the best results, including one-off bridges.
semantic asks an LLM to plan follow-up searches and incurs LLM calls.
Omitted/null leaves core resolution unchanged: semantic when semantic hops/config
is enabled, otherwise consensus. The measured fixture spike kept consensus:
bridge F1 improved by 22.92 points with relevance, but median hops increased from
1 to 3, exceeding the pre-registered one-extra-hop bound. This is a fixture result,
not a production or LoCoMo quality claim.
Invalid strategies return HTTP 400 naming all three values. A supplied strategy
with multi_hop=false is labelled in response inert_parameters; Python SDK
retains this in last_inert_parameters, and MCP echoes it.
CLI: sm search "which team owns checkout?" --multi-hop --max-hops 3 --hop-strategy relevance.
--max-hops accepts 1–10; --hop-strategy without --multi-hop is rejected.
Daemon, local fallback and remote wrapper paths carry the flags.