Store memory in one of two modes — single-memory (set top-level content) or batch (set memories: [...] for up to 500). Use this to persist important information for future recall.

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

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 id, 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({ memories: [{ content: "...", tags: ["import"] }, { content: "...", tags: ["import"] }] }) // Batch

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. 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.

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: "abc123" }) // Mode 1

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

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

• 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 a typed relationship between two memories. This builds a knowledge graph that improves recall by surfacing related context.

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: "bug-fix-123", memory2_id: "feature-456", type: "RELATES_TO", strength: 0.9 })

• associate_memories({ memory1_id: "new-decision", memory2_id: "old-decision", type: "EVOLVED_INTO", 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: "abc123", importance: 0.95 }) // Increase importance

• update_memory({ memory_id: "abc123", tags: ["project-x", "critical", "auth"] }) // Add tags

• update_memory({ memory_id: "abc123", 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: "abc123" }) // 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({})