Recall

Check if the recall daemon is running and healthy.

The daemon provides fast (<10ms) memory storage by queueing operations and processing embeddings asynchronously.

Returns: Dictionary with: - running: Boolean indicating if daemon is running - status: Detailed status if running (uptime, queue stats, cache stats) - error: Error message if not running

Store a new memory with semantic indexing, deduplication, and automatic relationship inference.

FAST PATH: If daemon is running, queues for async embedding (<10ms response). The daemon handles embedding and storage in the background.

Auto-linking behavior:

• ALWAYS works using embedding similarity (no LLM required)

• Creates 'relates_to' edges for memories above similarity_threshold

• If LLM available, upgrades edge types to supersedes/contradicts/caused_by

• Set auto_link=False to disable automatic edge creation

Args: content: The memory content text memory_type: Type of memory (preference, decision, pattern, session) namespace: Scope of the memory (default from RECALL_DEFAULT_NAMESPACE config) importance: Importance score from 0.0 to 1.0 (default from RECALL_DEFAULT_IMPORTANCE config) metadata: Optional additional metadata as dict auto_link: If True, automatically create edges to similar memories (default: True) similarity_threshold: Minimum similarity for auto-linking, 0.0-1.0 (default: 0.6) max_auto_links: Maximum auto-created edges per memory (default: 5) use_llm_classification: If True, use LLM to refine edge types (default: True)

Returns: Result dictionary with: - success: Boolean indicating operation success - queued: True if queued via daemon (fast path) - queue_id: Queue ID if queued via daemon - id: Memory ID (if sync path used) - content_hash: Content hash for deduplication (sync path only) - auto_relationships: List of automatically inferred relationships (sync path only) - error: Error message (if failed)

Recall memories using semantic search with optional multi-hop graph expansion.

Performs semantic search using ChromaDB vector similarity, applies filters, and optionally expands results via graph edges using configurable multi-hop traversal.

Args: query: Search query text (will be embedded with mxbai query prefix) n_results: Maximum number of primary results (default: 5) namespace: Filter by namespace (optional, e.g., 'global' or 'project:myapp') memory_type: Filter by memory type (optional, e.g., 'preference', 'decision') min_importance: Minimum importance score filter (0.0 to 1.0, optional) include_related: If True, include related memories via graph edges (default: False) max_depth: Maximum number of hops for graph expansion (default: 1) max_expanded: Maximum number of expanded memories to return (default: 20) decay_factor: Factor by which relevance decays per hop (default: 0.7) include_edge_types: Optional list of edge types to include (None means all). Valid types: relates_to, supersedes, caused_by, contradicts exclude_edge_types: Optional list of edge types to exclude (None means none). Valid types: relates_to, supersedes, caused_by, contradicts

Returns: Dictionary with: - success: Boolean indicating operation success - memories: List of primary memory dicts with id, content, type, etc. - total: Total count of primary memories returned - score: Average similarity score of primary memories (or None) - expanded: List of expanded memory dicts (when include_related=True) with: - id: Memory ID - content: Memory content - type: Memory type - relevance_score: Combined relevance score (0.0 to 1.0) - hop_distance: Number of edges traversed to reach this memory - path: List of edge types in traversal order - explanation: Human-readable relevance explanation

Inspect the graph structure around a memory node.

Performs read-only breadth-first search from the origin memory, collecting all nodes and edges within max_depth hops. Returns structured data for visualization including Mermaid diagram generation.

Args: memory_id: ID of the memory to start inspection from max_depth: Maximum number of hops to traverse (default: 2) direction: Edge traversal direction - "outgoing", "incoming", or "both" (default: "both") edge_types: Optional list of edge types to include (None means all). Valid types: relates_to, supersedes, caused_by, contradicts include_scores: If True, compute relevance scores for paths (default: True) decay_factor: Factor by which relevance decays per hop (default: 0.7) output_format: Output format - "json" or "mermaid" (default: "json")

Returns: Dictionary with: - success: Boolean indicating operation success - origin_id: The starting memory ID - nodes: List of node dicts with id, content_preview, type, confidence, importance - edges: List of edge dicts with id, source_id, target_id, edge_type, weight - paths: List of path dicts with node_ids, edge_types, total_weight, relevance_score - stats: Dict with node_count, edge_count, max_depth_reached, origin_id - mermaid: Mermaid diagram string (only when output_format='mermaid') - error: Error message (if failed)

Create a relationship between two memories.

Args: source_id: ID of the source memory target_id: ID of the target memory relation: Type of relationship (relates_to, supersedes, caused_by, contradicts) weight: Edge weight (default: 1.0)

Returns: Result dictionary with success status and edge_id

Delete edges (relationships) between memories.

Supports three deletion modes:

1. Direct ID: Delete a specific edge by its ID

2. Memory-based: Delete all edges connected to a memory

3. Pair: Delete edge(s) between two specific memories

Args: edge_id: Specific edge ID to delete (direct deletion mode) memory_id: Memory ID to delete all connected edges (memory-based mode) source_id: Source memory ID for pair deletion mode target_id: Target memory ID for pair deletion mode relation: Filter by relation type (optional). Valid: relates_to, supersedes, caused_by, contradicts direction: For memory_id mode: 'outgoing', 'incoming', or 'both' (default: 'both')

Returns: Result dictionary with: - success: Boolean indicating operation success - deleted_ids: List of edge IDs that were deleted - deleted_count: Number of edges deleted - error: Error message (if failed)

Examples: Delete by edge ID: edge_id=42 Delete all edges for memory: memory_id="mem_123" Delete specific relation: source_id="mem_123", target_id="mem_456", relation="contradicts"

Fetch relevant memories and format them for context injection.

Args: query: Optional search query to filter relevant memories project: Project namespace (auto-detected from cwd if not specified) token_budget: Maximum tokens for context (default from RECALL_DEFAULT_TOKEN_BUDGET config)

Returns: Dictionary with success status and formatted markdown context

Delete memories by ID or semantic search.

Golden rules (type=golden_rule or confidence >= 0.9) are protected from deletion unless force=True is specified.

Args: memory_id: Specific memory ID to delete (direct deletion mode). query: Search query to find memories to delete (search deletion mode). input: Smart parameter that auto-detects if value is an ID or query. namespace: Filter deletion to specific namespace (optional). n_results: Number of search results to delete in query mode (default: 5). confirm: If True, proceed with deletion (default: True). force: If True, allow deletion of golden rules (default: False).

Returns: Result dictionary with success status, deleted_ids, and deleted_count.

Note: If both memory_id and query are None but input is provided, the function auto-detects whether input is a memory ID or search query.

Record a file activity event.

Used by PostToolUse hooks to track what files have been accessed.

Args: file_path: Path to the file that was accessed action: Type of action (read, write, edit, multiedit) session_id: Optional session ID for grouping activities project_root: Optional project root directory file_type: Optional file type (e.g., 'python', 'typescript') metadata: Optional additional metadata

Returns: Result dictionary with success status and activity_id

Get recently accessed files with aggregated activity.

Args: project_root: Filter by project root (optional) limit: Maximum number of files to return (default: 20) days: Look back this many days (default: 14)

Returns: Dictionary with success status and list of recent files

Validate a memory and adjust its confidence score.

Adjusts confidence based on whether the memory was useful:

• Success: confidence += adjustment (max 1.0)

• Failure: confidence -= adjustment * 1.5 (min 0.0)

Automatically promotes to GOLDEN_RULE when confidence reaches 0.9.

Args: memory_id: ID of the memory to validate success: Whether the memory application was successful adjustment: Base confidence adjustment (default: 0.1)

Returns: Result with old/new confidence, promotion status, or error

Record that a memory is being applied.

Creates a validation event to track when a memory is used in practice. This starts the TRY phase of the validation loop.

Args: memory_id: ID of the memory being applied context: Description of how/where the memory is being applied session_id: Optional session identifier

Returns: Result with event ID or error

Record the outcome of a memory application and adjust confidence.

Records whether applying a memory succeeded or failed, creating a validation event and adjusting confidence accordingly.

Args: memory_id: ID of the memory that was applied success: Whether the application was successful error_msg: Optional error message if failed session_id: Optional session identifier

Returns: Result with updated confidence and promotion status

Detect memories that contradict a given memory.

Uses semantic search to find similar memories, then LLM reasoning to determine if they actually contradict each other.

Args: memory_id: ID of the memory to check for contradictions similarity_threshold: Minimum similarity for considering contradictions (default: 0.7) create_edges: Whether to create CONTRADICTS edges (default: True)

Returns: Result with list of contradicting memory IDs and edges created

Check if a memory should supersede another based on validation history.

A newer memory supersedes an older one when it consistently succeeds where the older one failed on similar topics.

Args: memory_id: ID of the (potentially newer) memory to check create_edge: Whether to create SUPERSEDES edge (default: True)

Returns: Result with superseded memory ID if applicable

Analyze the health of memories in the system.

Checks for unresolved contradictions, low-confidence memories, and stale memories that haven't been validated recently.

Args: namespace: Limit analysis to specific namespace (optional) include_contradictions: Check for contradictions (default: True) include_low_confidence: Find low-confidence memories (default: True) include_stale: Find stale memories (default: True) stale_days: Days without validation to consider stale (default: 30)

Returns: Dictionary with categorized issues and recommendations

Count memories with optional filters.

Provides a quick count of memories in the system, optionally filtered by namespace and/or memory type.

Args: namespace: Filter by namespace (optional, e.g., 'global' or 'project:myapp') memory_type: Filter by type (optional, e.g., 'preference', 'decision', 'golden_rule')

Returns: Dictionary with count and applied filters

List memories with filtering and pagination.

Browse memories in the system with optional filters and pagination. Useful for auditing, exploring, or debugging memory contents.

Args: namespace: Filter by namespace (optional) memory_type: Filter by type (optional) limit: Maximum number of results (default: 100, max: 1000) offset: Number of results to skip for pagination (default: 0) order_by: Field to sort by (default: 'created_at', options: 'created_at', 'accessed_at', 'importance', 'confidence') descending: Sort in descending order (default: True)

Returns: Dictionary with list of memories and pagination info

Get validation event history for a memory.

Shows the history of validation events (applied, succeeded, failed) for a specific memory. Useful for understanding why a memory has its current confidence score.

Args: memory_id: ID of the memory to get history for event_type: Filter by event type (optional: 'applied', 'succeeded', 'failed') limit: Maximum number of events to return (default: 50)

Returns: Dictionary with validation events and summary statistics