Reference
MCP Tools API Reference
š Repository : smartmemory-ai/smart-memory-mcp
š Issues : Report bugs or request features
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 (13 tools).PRO ā unlocked after login(api_key) (58 tools).PRO+ ā additionally requires SMARTMEMORY_MCP_FULL_TOOLS=true (89 tools).
All tools return strings (or, for get_working_context, a structured dict). Parameter types below are taken directly from the function signatures in smart-memory-mcp/smartmemory_mcp/tools/.
For the integration walkthrough, see guides/mcp-integration.mdapi/smart-memory.md
Tool Signature Description login(api_key: str)Authenticate with a SmartMemory API key. Restart server to unlock PRO tools. whoami()Show current session: user, team, tier, backend mode. switch_team(team_id: str)Switch to a different workspace/team.
{ "name" : "login" , "arguments" : { "api_key" : "sm_live_..." } } Tool Signature Description memory_ingest(content: str, memory_type: str = "semantic")Run content through the full 11-stage pipeline with extraction. memory_search(query: str, top_k: int = 5, memory_type: str = None, enable_hybrid: bool = True, catalog_mode: bool = True, decompose: bool = False, channel_weights: dict = None, multi_hop: bool = False, max_hops: int = 3, budget_ms: int = 1500)Semantic similarity search with optional hybrid / decompose / multi-hop. memory_recall(query: str, session_id: str = None, top_k: int = 5)Deprecated ā use get_working_context.get_working_context(session_id: str, query: str, k: int = 20, max_tokens: int = None, strategy: str = None) -> dictStructured surfacing response (CORE-MEMORY-DYNAMICS-1 M1a). memory_get(item_id: str)Retrieve a memory item by ID with full content and metadata. memory_feedback(search_session_id: str, result_used: list[str])Report which results from a previous memory_search were used. Registered unconditionally (before the PRO gate).
{ "name" : "memory_search" , "arguments" : { "query" : "auth caching" , "top_k" : 5 , "multi_hop" : true } } Tool Signature Description memory_add(content: str, memory_type: str = "semantic", metadata: dict = None, tags: list[str] = None)Add a memory item directly without the NLP pipeline. memory_update(item_id: str, content: str = None, metadata: dict = None, properties: dict = None, write_mode: str = None)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_distill(user_turn: str, assistant_turn: str, session_id: str = None)Ingest a conversation turn pair into pending memory. memory_ingest_conversation(turns: list, session_boundaries: list = None, conversation_id: str = None, session_dates: list = None, turns_per_chunk: int = 15, max_chunk_chars: int = 12000)Ingest a conversation as session chunks (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)Exact metadata key/value match.
Tool Signature Description memory_export(path: str)Export all memories to a JSONL file. memory_import(path: str)Import memories from a JSONL file, re-ingesting each. memory_migrate(target: str)Migrate all memories to a different backend (local or remote).
Tool Signature Description memory_auto(session_id: str = "", enabled: bool = True, recall_strategy: str = "topic_change", orient_budget: int = 1500, recall_budget: int = 500, observe_tool_calls: bool = True, distill_turns: bool = True, learn_from_errors: bool = True)Enable or disable automatic memory lifecycle for a session.
Tool Signature Description decision_create(content: str, decision_type: str = "inference", confidence: float = 0.8, evidence_ids: list[str] = None, domain: str = None, tags: list[str] = None, source_trace_id: str = None, rejected_alternatives: list[str] = None, rationale: str = None, constraints: list[str] = None)Create a new decision with provenance tracking. decision_get(decision_id: str)Retrieve a decision by ID. decision_list(domain: str = None, decision_type: str = None, min_confidence: float = 0.0, limit: int = 50)List active decisions with optional filtering. decision_search(topic: str, limit: int = 20)Search active decisions related to a topic. decision_supersede(decision_id: str, new_content: str, reason: str, new_decision_type: str = "inference", new_confidence: float = 0.8)Replace a decision; mark old as superseded. decision_retract(decision_id: str, reason: str)Retract a decision as no longer valid. decision_reinforce(decision_id: str, evidence_id: str)Record supporting evidence. decision_contradict(decision_id: str, evidence_id: str)Record contradicting evidence. decision_provenance(decision_id: str)Full provenance chain. decision_find_conflicts(decision_id: str)Find decisions that may conflict.
Tool Signature Description code_index(directory: str, repo_name: str = None, exclude_dirs: str = None)Index a Python codebase into the knowledge graph. code_search(query: str, entity_type: str = None, repo: str = None, limit: int = 20)Search indexed code entities. code_dead_code(repo: str, exclude_decorators: str = None, limit: int = 50)Find potentially dead (unreferenced) functions. code_dependencies(entity_name: str, direction: str = "both", repo: str = None)Trace what calls / imports / inherits what.
Tool Signature Description memory_anchor_set(content: str, anchor_type: str = "spec", session_id: str = "")Pin a requirement or constraint for a session. memory_anchor_list(session_id: str = "", anchor_type: str = None)List active anchors for a session. memory_anchor_clear(session_id: str = "", anchor_type: str = None)Deactivate anchors for a session. memory_anchor_graduate(session_id: str = "")Promote active anchors to persistent decisions. memory_anchor_check_drift(session_id: str = "", recent_outputs: list[str] = None)Check if recent outputs drifted from anchored requirements.
Tool Signature Description memory_plan_create(title: str, tasks: list[dict] = None, context: str = "", created_by: str = "")Create a plan with optional task nodes. memory_plan_get(plan_id: str)Get a plan with all its tasks. memory_plan_active()Get all active plans. memory_plan_update_task(plan_id: str, task_id: str, status: str)Update task status (pending / in_progress / complete / blocked). memory_log_failure(error_type: str, content: str, context: str, plan_id: str = None, task_id: str = None, attempted_fix: str = None, resolution: str = None)Log an agent failure for cross-session error recovery. memory_check_failure(error_type: str, context: str, top_k: int = 3)Check for matching past failures before retrying.
Tool Signature Description agent_set_recall_profile(agent_id: str, memory_type_weights: dict[str, float] = None)Set personality-aware re-ranking weights. agent_get_recall_profile(agent_id: str)Get an agent's recall profile. agent_evaluation_get(agent_id: str, dimension: str, domain: str)Get the current evaluation score for an agent on a (dimension, domain) slot (CORE-AGENT-2).
Tool Signature Description memory_ingest_structured(data: dict, schema_name: str)Ingest structured data via a registered handler, bypassing NLP. memory_ingest_document(source: str, source_type: str = "auto", chunk_size: int = 2000, chunk_strategy: str = "paragraph", reference: bool = False)Ingest a document from a URL or file path.
Tool Signature Description memory_resolve_aliases(dry_run: bool = False, disambiguate: bool = False)Merge alias entities into their canonical nodes across the graph.
Tool Signature Description pattern_query(scope: str = None, severity: str = None, free_text: str = None, limit: int = 100)Query the graph-backed adherence pattern catalog (filters are conjunctive). pattern_get(pattern_id: str)Retrieve a single pattern by ID. pattern_list(limit: int = 200)List patterns in the catalog. memory_get_violation_patterns(rule_id: str = None, rule_type: str = "feedback", memory_dir: str = None)Return the ## Detection patterns catalog from local rule files (distinct from the graph-backed catalog).
Tool Signature Description reasoning_challenge(assertion: str, memory_type: str = "semantic", use_llm: bool = True)Challenge an assertion against existing knowledge. reasoning_resolve_conflict(existing_item_id: str, new_fact: str, use_wikipedia: bool = True, use_llm: bool = True)Resolve conflict via Wikipedia, LLM, grounding, or recency. reasoning_query(query: str, top_k: int = 10)Route a query to the cheapest effective retrieval method. reasoning_proof_tree(decision_id: str, max_depth: int = 5)Build an auditable proof tree for a decision. reasoning_fuzzy_confidence(decision_id: str)Multi-dimensional confidence (evidence, recency, consensus, directness). reasoning_extract_trace(content: str, min_steps: int = 2, use_llm_detection: bool = True)Extract chain-of-thought reasoning traces from content. reasoning_query_traces(query: str, limit: int = 10)Query stored reasoning traces.
Tool Signature Description evolution_trigger()Run a full evolution cycle (clustering, dedup, consolidation). evolution_dream()Deprecated ā routing now happens at-ingest (CORE-MEMORY-DYNAMICS-1 M1b).evolution_status()Status of memory evolution processes. evolution_synthesize_opinions()Detect patterns in episodic memories and form opinions. evolution_synthesize_observations()Build entity summaries from scattered facts. evolution_reinforce_opinions()Update confidence scores based on new evidence. clustering_run(distance_threshold: float = 0.1)Merge duplicate entities by vector similarity.
Tool Signature Description insight_health()Memory health summary ā counts, score, detected issues. insight_reflect(top_k: int = 10)Identify key concepts, top entities, dominant topics. insight_maintenance_status(stale_threshold_days: int = 90, low_confidence_threshold: float = 0.5)Orphaned, stale, low-confidence counts. insight_plugins()List available extractors and enrichers. insight_personalize(traits: dict = None, preferences: dict = None)Apply personalization for retrieval. insight_feedback(feedback: dict = None, memory_type: str = "semantic")Update memory system based on user feedback. insight_ground(item_id: str, source_url: str)Ground a memory item to an external URL.
Tool Signature Description dev_record_decision(title: str, context: str, decision: str, rationale: str, alternatives: str = None, feature_id: str = None, tags: list[str] = None)Record an architectural decision as a decision memory. dev_query_decisions(query: str, feature_id: str = None, since: str = None, limit: int = 5)Search past decisions by keyword, feature, or time range. dev_save_session(summary: str, key_findings: list[str] = None, files_modified: list[str] = None, next_steps: list[str] = None, tags: list[str] = None)Save a development session summary as episodic memory. dev_load_context(topic: str, sessions: int = 3, include_decisions: bool = True)Load recent session context and related decisions. dev_record_pattern(name: str, description: str, example: str = None, applies_to: str = None, tags: list[str] = None)Record a code pattern as procedural memory. dev_log_friction(description: str, category: str, severity: str = "medium", context: str = None)Log a friction event during development.
Tool Signature Description zettel_backlinks(note_id: str)Notes that link TO this note. zettel_connections(note_id: str)All connections (backlinks + forward links). zettel_clusters(min_size: int = 3)Detect knowledge clusters in the Zettelkasten. zettel_discover(note_id: str, min_surprise: float = 0.5)Find unexpected (serendipitous) connections.
All tools follow standard MCP tools/call framing:
{ "jsonrpc" : "2.0" , "id" : 1 , "method" : "tools/call" , "params" : { "name" : "memory_ingest" , "arguments" : { "content" : "Alice met Bob at OpenAI in Paris." , "memory_type" : "episodic" } } }