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.

Returns compact previews by default to reduce context usage. Use content_mode="full" when you need the complete content. Use memory_get to fetch full content for specific IDs.

Args: query: Optional text search query metadata_filters: Optional metadata filters limit: Maximum results (default: 20). Pass -1 for unlimited. offset: Number of filtered 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) content_mode: "preview" (default) returns truncated content_preview; "full" returns complete content preview_chars: Max chars for preview (default: 120, ignored when content_mode="full") fields: Optional list of fields to return (e.g. ["id","content_preview","tags"]). None returns all fields. follow: Lineage mode — "latest" resolves each result to its current version, "active" excludes superseded memories, "full_history" expands supersession chains.

[Deprecated] List memories in compact format (id, preview, tags only).

Prefer memory_list which now defaults to compact previews with richer fields and configurable content_mode/preview_chars.

Returns minimal fields: id, content preview (first 80 chars), tags, and created_at.

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.

Intelligently absorb facts into memory with dedup and consolidation.

For each fact: searches for similar existing memories, classifies the relationship via LLM (duplicate/update/contradict/related/new), then takes the appropriate action. Related new facts are automatically consolidated into single, richer memories via LLM synthesis.

Args: facts: List of fact strings to absorb (can be granular — related ones get merged) source: Origin of facts — "manual", "session_end", "post_tool", "import" confidence: Caller's certainty about these facts (0.0-1.0, default: 0.8) context: Optional surrounding context to help disambiguate facts metadata: Optional metadata to attach to created memories tags: Optional tags to attach to created memories dry_run: If True, preview what would happen without writing anything

Store a structured document as a root memory + searchable fragments.

Parses markdown into typed fragments (claims, plan items, references, risks, section chunks) that are individually searchable while the full document remains retrievable as a unit.

Args: content: Full markdown document content document_key: Stable identifier (e.g. "research/memora-enhancements-2026-04-08") version: Document version (default: 1). If >1, supersedes previous version. tags: Tags applied to root and fragments metadata: Additional metadata merged into root and fragments skip_fragment_crossrefs: If True, fragments skip crossref computation (default: True)

Returns: {document_key, root_id, fragment_count, node_map: {node_kind: [ids]}}

Retrieve a stored document and its fragments by document key.

Args: document_key: The document identifier used during storage content_mode: "preview" (default) or "full" for fragment content preview_chars: Max chars for preview mode (default: 120) node_kinds: Optional filter — e.g. ["claim", "plan_item"] for specific fragment types version: Optional version filter. If omitted, returns the latest version.

Returns: {root: {...}, fragments: [...] ordered by ordinal, document_key, version}

Delete a stored document and all its fragments.

Args: document_key: The document identifier version: Optional — delete only this version. If omitted, deletes all versions.

Returns: {deleted_roots: count, deleted_fragments: count, deleted_ids: [...]}

Retrieve a single memory by id (full content by default).

Args: memory_id: ID of the memory to retrieve include_images: If False, strip image data from metadata to reduce response size fields: Optional list of fields to return (e.g. ["id","content","tags"]). None returns all fields. follow: Lineage mode — "latest" resolves to the current version (walks supersedes chains), "full_history" adds a "history" key with all versions from root to leaf.

Update an existing memory. Only provided fields are updated.

Delete a memory by id.

Args: memory_id: Memory ID to delete force: If True, allow deleting document fragments/roots. Use memory_delete_document() instead for clean document removal.

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.

Returns compact previews by default. Use content_mode="full" for complete content.

Args: query: Search query text top_k: Maximum number of results (default: 5) metadata_filters: Optional metadata filters min_score: Minimum similarity score threshold content_mode: "preview" (default) returns truncated content_preview; "full" returns complete content preview_chars: Max chars for preview (default: 300, ignored when content_mode="full") fields: Optional list of fields to return. Include "score" to keep {memory, score} envelope; omit "score" for flat list of memory dicts. follow: Lineage mode — "latest" resolves each result to its current version, "active" excludes superseded memories, "full_history" expands supersession chains.

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.

Returns compact previews by default. Use content_mode="full" for complete content. Use memory_get to fetch full content for specific IDs.

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) content_mode: "preview" (default) returns truncated content_preview; "full" returns complete content preview_chars: Max chars for preview (default: 300, ignored when content_mode="full") fields: Optional list of fields to return. Include "score" to keep {memory, score} envelope; omit "score" for flat list of memory dicts. follow: Lineage mode — "latest" resolves each result to its current version, "active" excludes superseded memories, "full_history" expands supersession chains.

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.

Consistency: the related graph is eventually consistent. When a new memory A is created or updated with references to an existing B, A.related is computed fresh but B.related is not re-cascaded — it stays valid until either a full rebuild or an explicit refresh. Pass refresh=True to recompute this memory's crossrefs on the fly (the strong-consistency path). For a full rebuild across the store, call memory_rebuild_crossrefs.

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

Use this periodically (or after bulk imports) to close the eventual-consistency gap in the related graph — see memory_related for the consistency model.

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.

Detect memories that supersede (update/replace) other memories.

Scans existing memories for pairs where one is an evolved/updated version of another, then creates 'supersedes' edges between them. Complements memory_absorb which only catches supersessions at write time.

Uses neutral LLM classification (not biased by timestamps) to determine both the relationship type and direction.

Args: min_similarity: Minimum embedding similarity to consider (default: 0.55) limit: Maximum pairs to analyze with LLM (default: 20) dry_run: If True, preview detections without creating edges (default: True) tags_any: Only consider memories with any of these tags min_confidence: Minimum LLM confidence to accept (default: 0.75)

Returns: Dictionary with candidates found, analyzed count, detected supersessions, and detailed results for each pair.

Rate limited: 120s cooldown.

Re-tag existing memories with project-prefixed tags.

Uses deterministic normalization to prefix generic tags (e.g. "plan" → "memora/plan") when the memory content clearly belongs to a specific project. No LLM calls.

Idempotent: re-running produces the same result.

Args: dry_run: If True, preview changes without writing (default: True)

Returns: Dictionary with processed count, changed count, and list of changes.

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