Memory

SDK reference for memory operations

Overview

Internal memory and knowledge graph management

• Category: internal
• Auth Required: No
• Supported Modes: standard, delegated, service

Operations

create

Create a new memory entity in the knowledge graph. Use the type field to specify what kind of memory (note, idea, shopping_item, etc.). For tasks with assignment or timing features, use createTask instead. All memory types can be queried, updated, and deleted using the standard operations.

Arguments:

• type (string, required): Memory subtype: "note" (general notes), "idea" (concepts/ideas), "shopping_item" (shopping list), "topic" (general knowledge), "document" (documents), "contact" (people), "event" (calendar items). For tasks with assignment, use createTask instead.
• content (string, required): Main content/description of the memory
• metadata (object, optional): Additional metadata (e.g., priority, deadline, tags, etc.)

Returns:

AdapterOperationResult - Returns FLAT structure with: id, type, name, content, status, priority, graphId, createdAt, createdByUserId, createdByName, tags[]. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.create({
  type: "example",
  content: "example"
});

createTask

Create a task in the knowledge graph. Tasks are a specialized memory type with assignment, timing, priority, and status lifecycle. Use this instead of create when you need task-specific features like assigning to users. Tasks can be queried, updated, and deleted using the standard memory operations (query, update, delete) with type="task". For group contexts, the task is stored in the group's shared graph.

Arguments:

• content (string, required): Task description/title - what needs to be done. IMPORTANT: Write task content from a neutral perspective without possessive pronouns (his/her/their). The assignee will see this exact text, so "fold dresses" is correct, NOT "fold her dresses". Avoid phrases like "remind him to", "help her with", etc.
• assignedTo (string, optional): Username of the person to assign this task to (group contexts only). System resolves username to user ID.
• dueAt (string, optional): Due date/time in ISO 8601 format (e.g., "2024-01-15T10:00:00Z") or natural language that will be parsed
• priority (string, optional): Task priority: "high", "medium", or "low"
• tags (array, optional): Tags/labels for categorization (e.g., ["work", "urgent"])

Returns:

AdapterOperationResult - Returns FLAT structure with: id, type, content, status, priority, graphId, createdAt, createdByUserId, createdByName, assignedToUserId, assignedToName, assignmentWarning, dueAt, tags[]. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.createTask({
  content: "example"
});

search

Semantic search across memory entities with advanced filtering. IMPORTANT: Search results return TRUNCATED content (max 300 chars) to prevent huge payloads. To get the full untruncated text of a specific entity, use findOne with the entity ID after searching. Recommended workflow: (1) Use search to find matching entities, (2) Use findOne with { filters: { id: "entity_id" } } to retrieve full content for entities you need.

Arguments:

• query (string, required): Search query text for semantic matching
• types (array, optional): Filter by entity types (e.g., ["TASK", "NOTE", "IDEA"])
• startTime (number, optional): Filter entities created after this timestamp (Unix milliseconds)
• endTime (number, optional): Filter entities created before this timestamp (Unix milliseconds)
• propertyFilters (object, optional): Filter by entity properties: { status: ["completed"], tags: ["urgent"], priority: ["high"], roles: ["task"], contexts: ["work"] }
• limit (number, optional): Maximum number of results (default: 50, max: 100)

Returns:

AdapterOperationResult - Returns { query, count, results[] }. Each result has FLAT fields: id, type, name, description (truncated), status, priority, graphId, createdAt, score. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.search({
  query: "example"
});

query

Query memory entities with filters. Returns lightweight summaries with TRUNCATED content (max 200 chars) to prevent large payloads. Use type="task" to list all tasks (including those created via createTask). To get full untruncated content for a specific entity, use findOne with the entity ID.

Arguments:

• type (string, optional): Semantic type filter (e.g., "task", "note", "idea", "reminder", "contact", "document"). Matches against meta_item_type, subType, or semantic_roles
• filters (object, optional): Additional filters (not yet implemented)
• limit (number, optional): Maximum results (default: 50, max: 100)
• offset (number, optional): Pagination offset for fetching more results (default: 0)

Returns:

AdapterOperationResult - Returns { type, count, offset, limit, entities[] }. Each entity has FLAT fields: id, type, name, description (truncated), status, priority, graphId, createdAt. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.query({});

findOne

Find a single entity by ID or name. Returns the FULL untruncated entity content. Use this after search or query to retrieve complete content for a specific entity (since those operations return truncated results to prevent large payloads).

Arguments:

• filters (object, required): Filter criteria. Use { id: "entity_id" } to find by ID (recommended), or { name: "entity name" } to find by name.

Returns:

AdapterOperationResult - Returns FLAT structure with: id, type, name, content (full), status, priority, graphId, createdAt, updatedAt, createdByUserId, createdByName, assignedToUserId, assignedToName, dueAt, tags[]. No nested objects. Null if not found.

Response Fields:

Example:

const result = await mirra.memory.findOne({
  filters: {}
});

update

Update an existing memory entity. Works with all memory types including tasks created via createTask. Use this to mark tasks complete, update content, or modify metadata.

Arguments:

• id (string, required): Entity ID to update
• type (string, optional): Entity type
• content (string, optional): Updated content
• metadata (object, optional): Updated metadata

Returns:

AdapterOperationResult - Returns FLAT structure with: id, updated, updatedAt. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.update({
  id: "abc123"
});

delete

Delete a memory entity. Works with all memory types including tasks, notes, ideas, etc.

Arguments:

• id (string, required): Entity ID to delete

Returns:

AdapterOperationResult - Returns FLAT structure with: id, deleted, deletedAt. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.delete({
  id: "abc123"
});

share

Share a memory entity with another graph (group or contact). Only the creator can share memories. Recipients can view and complete tasks but cannot edit or delete.

Arguments:

• entityId (string, required): Entity ID to share
• targetGraphId (string, required): Target graph ID to share with (group ID or user contact graph ID)
• shareReason (string, optional): Optional reason for sharing

Returns:

AdapterOperationResult - Returns FLAT structure with: entityId, success, message, graphIds[], targetGraphId, sharedAt. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.share({
  entityId: "abc123",
  targetGraphId: "abc123"
});

unshare

Remove sharing of a memory entity from a graph. Only the creator can unshare. Cannot unshare from the primary graph (where it was created).

Arguments:

• entityId (string, required): Entity ID to unshare
• graphId (string, required): Graph ID to remove sharing from

Returns:

AdapterOperationResult - Returns FLAT structure with: entityId, success, message, graphIds[], removedGraphId. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.unshare({
  entityId: "abc123",
  graphId: "abc123"
});

listGraphs

List all graphs a memory entity is shared with, including share history and metadata.

Arguments:

• entityId (string, required): Entity ID to list graphs for

Returns:

AdapterOperationResult - Returns { entityId, primaryGraphId, totalGraphs, graphs[] }. Each graph has FLAT fields: graphId, graphType, graphName, isPrimary, sharedAt, sharedByUserId. No nested objects.

Response Fields:

Example:

const result = await mirra.memory.listGraphs({
  entityId: "abc123"
});