memora

Create a new memory entry.

Args: content: The memory content text metadata: Optional metadata dictionary tags: Optional list of tags suggest_similar: If True, find similar memories and suggest consolidation (default: True) similarity_threshold: Minimum similarity score for suggestions (default: 0.2) response_mode: "full" (default) or "minimal" response payload size

Create a new issue/bug memory.

Args: content: Description of the issue status: Issue status - "open" (default) or "closed" closed_reason: If closed, the reason - "complete" or "not_planned" severity: Issue severity - "critical", "major", "minor" (default) component: Component/area affected (e.g., "graph", "storage", "api") category: Issue category (e.g., "bug", "enhancement", "performance")

Returns: Created issue memory with auto-assigned tag "memora/issues"

Create a new TODO/task memory.

Args: content: Description of the task status: Task status - "open" (default) or "closed" closed_reason: If closed, the reason - "complete" or "not_planned" priority: Task priority - "high", "medium" (default), "low" category: Task category (e.g., "cloud-backend", "graph-visualization", "docs")

Returns: Created TODO memory with auto-assigned tag "memora/todos"

Create a new section/subsection header memory.

Section memories are organizational placeholders that:

• Are NOT visible in the graph visualization

• Are NOT included in duplicate detection

• Do NOT compute embeddings or cross-references

Args: content: Title/description of the section section: Parent section name (e.g., "Architecture", "API") subsection: Subsection path (e.g., "endpoints/auth")

Returns: Created section memory with auto-assigned tag "memora/sections"

List memories, optionally filtering by substring query or metadata.

Args: query: Optional text search query metadata_filters: Optional metadata filters limit: Maximum number of results to return (default: unlimited) offset: Number of results to skip (default: 0) date_from: Optional date filter (ISO format or relative like "7d", "1m", "1y") date_to: Optional date filter (ISO format or relative like "7d", "1m", "1y") tags_any: Match memories with ANY of these tags (OR logic) tags_all: Match memories with ALL of these tags (AND logic) tags_none: Exclude memories with ANY of these tags (NOT logic) sort_by_importance: Sort results by importance score (default: False, sorts by date)

List memories in compact format (id, preview, tags only) to reduce context usage.

Returns minimal fields: id, content preview (first 80 chars), tags, and created_at. This tool is useful for browsing memories without loading full content and metadata.

Args: query: Optional text search query metadata_filters: Optional metadata filters limit: Maximum number of results to return (default: unlimited) offset: Number of results to skip (default: 0) date_from: Optional date filter (ISO format or relative like "7d", "1m", "1y") date_to: Optional date filter (ISO format or relative like "7d", "1m", "1y") tags_any: Match memories with ANY of these tags (OR logic) tags_all: Match memories with ALL of these tags (AND logic) tags_none: Exclude memories with ANY of these tags (NOT logic)

Create multiple memories in one call.

Delete multiple memories by id.

Retrieve a single memory by id.

Args: memory_id: ID of the memory to retrieve include_images: If False, strip image data from metadata to reduce response size

Update an existing memory. Only provided fields are updated.

Delete a memory by id.

Return the allowlisted tags.

Return stored tags organised as a namespace hierarchy.

Validate stored tags against the allowlist and report invalid entries.

Return memories organised into a hierarchy derived from their metadata.

Args: compact: If True (default), return only id, preview (first 80 chars), and tags per memory to reduce response size. Set to False for full memory data.

Perform a semantic search using vector embeddings.

Perform a hybrid search combining keyword (FTS) and semantic (vector) search.

Uses Reciprocal Rank Fusion (RRF) to merge results from both search methods, providing better results than either method alone.

Args: query: Search query text semantic_weight: Weight for semantic results (0-1). Higher values favor semantic similarity. Keyword weight = 1 - semantic_weight. Default: 0.6 (60% semantic, 40% keyword) top_k: Maximum number of results to return (default: 10) min_score: Minimum combined score threshold (default: 0.0) metadata_filters: Optional metadata filters date_from: Optional date filter (ISO format or relative like "7d", "1m", "1y") date_to: Optional date filter (ISO format or relative) tags_any: Match memories with ANY of these tags (OR logic) tags_all: Match memories with ALL of these tags (AND logic) tags_none: Exclude memories with ANY of these tags (NOT logic)

Returns: Dictionary with count and list of results, each containing score and memory

Recompute embeddings for all memories. Rate limited: 300s cooldown.

Return cross-referenced memories for a given entry.

Recompute cross-reference links for all memories. Rate limited: 300s cooldown.

Get statistics and analytics about stored memories.

Analyze stored memories and produce actionable insights.

Returns activity summary, open items, consolidation suggestions, and optional LLM-powered pattern detection.

Args: period: Time period to analyze (e.g., "7d", "1m", "1y") include_llm_analysis: If True, use LLM to detect patterns and themes

Returns: Dictionary with: - activity_summary: Created counts by type and tag - open_items: Open TODOs and issues with stale detection - consolidation_candidates: Similar memory pairs that could be merged - llm_analysis: Themes, focus areas, gaps, and summary (or null) Rate limited: 120s cooldown.

Boost a memory's importance score.

Manually increase a memory's base importance to make it rank higher in importance-sorted searches. The boost is permanent and cumulative.

Args: memory_id: ID of the memory to boost boost_amount: Amount to add to base importance (default: 0.5) Common values: 0.25 (small), 0.5 (medium), 1.0 (large)

Returns: Updated memory with new importance score, or error if not found

Create an explicit typed link between two memories.

Args: from_id: Source memory ID to_id: Target memory ID edge_type: Type of relationship. Options: - "references" (default): General reference - "implements": Source implements/realizes target - "supersedes": Source replaces/updates target - "extends": Source builds upon target - "contradicts": Source conflicts with target - "related_to": Generic relationship bidirectional: If True, also create reverse link (default: True)

Returns: Dict with created links and their types

Remove a link between two memories.

Args: from_id: Source memory ID to_id: Target memory ID bidirectional: If True, also remove reverse link (default: True)

Returns: Dict with removed links

Detect clusters of related memories.

Args: min_cluster_size: Minimum memories to form a cluster (default: 2) min_score: Minimum similarity score to consider connected (default: 0.3) algorithm: "connected_components" (default) or "louvain" Louvain uses embedding similarity for content-based clustering.

Returns: List of clusters with member IDs, sizes, and common tags

Find potential duplicate memory pairs with optional LLM-powered comparison.

Scans cross-references to find memory pairs with similarity >= threshold, then optionally uses LLM to semantically compare them. Uses the same threshold (0.85) as the graph UI duplicate detection.

Args: min_similarity: Minimum similarity score to consider (default: 0.85) max_similarity: Maximum similarity score (default: 1.0, kept for backward compatibility) limit: Maximum pairs to analyze (default: 10) use_llm: Whether to use LLM for semantic comparison (default: True)

Returns: Dictionary with: - pairs: List of potential duplicate pairs with analysis - total_candidates: Total pairs found - analyzed: Number of pairs analyzed with LLM - llm_available: Whether LLM comparison was available

Rate limited: 120s cooldown.

Merge source memory into target, then delete source.

Combines two memories into one, preserving content and metadata.

Args: source_id: Memory ID to merge from (will be deleted) target_id: Memory ID to merge into (will be updated) merge_strategy: How to combine content: - "append": Append source content to target (default) - "prepend": Prepend source content to target - "replace": Replace target content with source

Returns: Updated target memory and deletion confirmation

Export all memories to JSON format for backup or transfer. Rate limited: 60s cooldown.

Upload an image file directly to R2 storage.

Uploads a local image file to R2 and returns the r2:// reference URL that can be used in memory metadata.

Args: file_path: Absolute path to the image file to upload memory_id: Memory ID this image belongs to (used for organizing in R2) image_index: Index of image within the memory (default: 0) caption: Optional caption for the image

Returns: Dictionary with r2_url (the r2:// reference) and image object ready for metadata

Migrate existing base64 images to R2 storage.

Scans all memories and uploads any base64-encoded images to R2, replacing the data URIs with R2 URLs.

Args: dry_run: If True, only report what would be migrated without making changes

Returns: Dictionary with migration results including count of migrated images

Rate limited: 300s cooldown.

Export memories as interactive HTML knowledge graph.

Args: output_path: Path to save HTML file (default: ~/memories_graph.html) min_score: Minimum similarity score for edges (default: 0.25)

Returns: Dictionary with path, node count, edge count, and tags

Import memories from JSON format. Rate limited: 60s cooldown.

Args: data: List of memory dictionaries with content, metadata, tags, created_at strategy: "replace" (clear all first), "merge" (skip duplicates), or "append" (add all)

Poll for memory events (e.g., shared-cache notifications).

Args: since_timestamp: Only return events after this timestamp (ISO format) tags_filter: Only return events with these tags (e.g., ["shared-cache"]) unconsumed_only: Only return unconsumed events (default: True)

Returns: Dictionary with count and list of events

Mark events as consumed.

Args: event_ids: List of event IDs to mark as consumed

Returns: Dictionary with count of cleared events