Store memory in one of two modes — single-memory (set top-level content) or batch (set memories: [...] for up to 500).

Mode 1 — Single (default): pass top-level content plus any optional fields (tags, importance, metadata, type, confidence, embedding, t_valid, t_invalid, etc.).

Mode 1b — Supersede/correct: pass top-level content plus supersedes_memory_id. The server stores the replacement, marks the old memory invalid with t_invalid=now, merges supersede metadata, and associates old → new with INVALIDATED_BY (default) or EVOLVED_INTO.

Mode 2 — Batch: pass memories: [{ content, tags?, importance?, metadata?, timestamp?, type?, confidence? }, ...] to store up to 500 memories in one request. Faster for bulk ingestion (imports, benchmark seeding). Batch mode does NOT accept embedding, t_valid, or t_invalid per-item — use single mode for those.

Content size guidelines (per item):

• Target: 150-300 characters (one meaningful paragraph)

• Maximum: 500 characters (auto-summarized if exceeded)

• Hard limit: 2000 characters (rejected)

• Format: "Brief title. Context and details. Impact/outcome."

When to use:

• After making a decision: store the reasoning and outcome

• When discovering a pattern: store the pattern and where it applies

• After fixing a bug: store the root cause and solution

• When learning user preferences: store what they prefer and why

• For bulk ingestion (imports, seeding): use batch mode

Examples:

• store_memory({ content: "Chose PostgreSQL over MongoDB for user service. Need ACID for transactions.", tags: ["architecture", "database"], importance: 0.9 })

• store_memory({ content: "User prefers early returns over nested conditionals.", tags: ["code-style"], importance: 0.7 })

• store_memory({ content: "User now prefers SQLite for small local tools.", supersedes_memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", supersede_reason: "Correction from user" })

Recall memories from AutoMem in one of three modes. The mode is selected by which params you pass.

Mode 1 — ID fetch: pass memory_id to retrieve a single memory by ID. All other params are ignored. Routes to GET /memory/{id} and updates last_accessed.

Mode 2 — Tag enumeration: pass tags + exhaustive: true for paginated exact-match listing (NOT ranked retrieval). Use this for cleanup/audit workflows where ranked retrieval silently undercounts large tag sets. Pair with limit (≤200) and offset. Returns has_more/limit/offset page metadata; next page at next_offset. Tag matching is exact, case-insensitive, any-of mode — tag_match: "prefix" and tag_mode: "all" are rejected in this mode.

Mode 3 — Ranked retrieval (default): hybrid search across vector, keyword, tags, recency, and optional graph expansion. The primary tool for finding relevant context. By default, ranked recall requests current active memories only; set current_only: false for audits.

When to use ranked (mode 3):

• At conversation start: recall context about the current project/topic

• Before making decisions: check for past decisions on similar topics

• When debugging: search for similar past errors and their solutions

• For complex questions: use expand_entities for multi-hop reasoning

When to use enumeration (mode 2): when you need to know how many memories carry a tag, or to walk all of them for cleanup/migration. Ranked recall ignores low-importance hits — enumeration does not.

Examples:

• recall_memory({ query: "database architecture decisions", tags: ["my-project"], limit: 5 })

• recall_memory({ memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91" }) // Mode 1

• recall_memory({ tags: ["benchmark-test"], exhaustive: true, limit: 50 }) // Mode 2 (add offset for later pages)

• recall_memory({ query: "auth", exclude_tags: ["deprecated"] }) // Mode 3 with exclusion

• recall_memory({ query: "What is Sarah's sister's job?", expand_entities: true }) // Mode 3 multi-hop

Create typed relationships between memories. This builds a knowledge graph that improves recall by surfacing related context. Supports single-pair mode or batch mode with associations[] (max 500).

When to use:

• After storing a new memory: link it to related existing memories

• When a bug fix relates to an original feature implementation

• When a new decision updates or invalidates a previous one

• To connect patterns with their concrete examples

Authorable relationship types:

• RELATES_TO: General relationship (default)

• LEADS_TO: Causal relationship (A caused B)

• OCCURRED_BEFORE: Temporal ordering

• PREFERS_OVER: Chosen alternative

• EXEMPLIFIES: Concrete example of a pattern

• CONTRADICTS: Conflicts with another memory

• REINFORCES: Strengthens another memory's validity

• INVALIDATED_BY: Superseded by another memory

• EVOLVED_INTO: Updated version of a concept

• DERIVED_FROM: Implementation of a decision/pattern

• PART_OF: Component of a larger effort

Read-only/internal relations:

• System/internal relations such as SIMILAR_TO, PRECEDED_BY, EXPLAINS, SHARES_THEME, PARALLEL_CONTEXT, and DISCOVERED may appear in recall results, but they are not valid inputs for associate_memories.

Examples:

• associate_memories({ memory1_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", memory2_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", type: "RELATES_TO", strength: 0.9 }) // bug fix → feature

• associate_memories({ memory1_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", memory2_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", type: "EVOLVED_INTO", strength: 0.8 }) // old decision → new

• associate_memories({ associations: [{ memory1_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", memory2_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", type: "RELATES_TO", strength: 0.8 }] })

Update an existing memory's content, tags, importance, or metadata. Use this to correct or enhance memories rather than storing duplicates.

When to use:

• To correct inaccurate information in a memory

• To add tags that were forgotten

• To adjust importance based on new understanding

• To add metadata after the fact

Examples:

• update_memory({ memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", importance: 0.95 }) // Increase importance

• update_memory({ memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", tags: ["project-x", "critical", "auth"] }) // Add tags

• update_memory({ memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", content: "Updated: PostgreSQL chosen for ACID + team expertise" })

Delete a memory by ID (memory_id) or bulk-delete by tag (tags). Use sparingly — consider update_memory instead.

Mode 1 — Single (default): pass memory_id to delete one memory and its embedding. Idempotent: re-running on the same ID is a no-op.

Mode 2 — Bulk-by-tag: pass tags: [...] to delete ALL memories tagged with ANY of these tags. Tag matching is exact (case-insensitive), any-of mode. There is NO dry-run. This can delete thousands of memories in one call. NOT idempotent in practice — re-running may catch new memories that were tagged the same way after the first call. Verify with recall_memory({ tags, exhaustive: true }) first if uncertain.

When to use:

• Memory contains incorrect information that can't be corrected (Mode 1)

• Memory is a duplicate (Mode 1)

• Cleanup of benchmark/test data scoped by tag (Mode 2)

• Removing all memories under a deprecated tag namespace (Mode 2)

Examples:

• delete_memory({ memory_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91" }) // Mode 1

• delete_memory({ tags: ["benchmark-test"] }) // Mode 2, bulk by tag

Check the health status of the AutoMem service and its connected databases (FalkorDB graph + Qdrant vectors).

When to use:

• Before a session to verify the memory service is available

• When memory operations are failing unexpectedly

• To check storage statistics

Example:

• check_database_health({})