Memory Overview

Store, search, and manage knowledge in your personal graph with semantic retrieval

The memory adapter provides access to Mirra's internal knowledge graph, enabling you to create, search, update, and delete memory entities. The knowledge graph stores structured information with semantic embeddings, supporting both keyword search and vector-based semantic retrieval.

What is Memory?

The memory system is Mirra's core knowledge storage layer, built on top of Neo4j graph database. It stores various types of entities (tasks, notes, ideas, shopping items, contacts, topics) with relationships and metadata, making information semantically searchable and contextually relevant.

When you create a memory, Mirra performs several operations:

Entity Creation - Creates a node in the knowledge graph with the specified type and content
Keyword Extraction - Generates searchable keywords from the content
Embedding - Creates vector embeddings for semantic search (when available)
Relationship Linking - Automatically links related entities (e.g., tasks to contacts)
Graph Assignment - Associates the memory with a specific graph ID for access control

Syntax

Creating a Memory

await mirra.memory.create({
  type: "task",
  content: "Review quarterly reports by Friday",
  metadata: {
    priority: "high",
    deadline: "2024-01-26"
  }
});

Memory Structure

{
  type: string;        // Memory subtype (task, note, idea, shopping_item, etc.)
  content: string;     // Main content/description
  metadata?: {         // Optional metadata
    priority?: "low" | "medium" | "high";
    deadline?: string;
    tags?: string[];
    status?: "open" | "in_progress" | "completed";
    // ... type-specific fields
  };
}

Memory Types

The memory system supports several predefined memory types, each optimized for specific use cases:

Tasks

Tasks represent actionable items with deadlines, priorities, and completion tracking.

await mirra.memory.create({
  type: "task",
  content: "Prepare presentation for Monday meeting",
  metadata: {
    priority: "high",
    deadline: "2024-01-22",
    status: "in_progress"
  }
});

Task-specific metadata:

priority - Task importance (low, medium, high)
deadline - Due date (ISO 8601 format)
status - Current state (open, in_progress, completed, cancelled)
effort_level - Estimated effort (low, medium, high)
assigned_to - User ID for delegation

Notes

Notes store general information, observations, and reference material.

await mirra.memory.create({
  type: "note",
  content: "Meeting notes from project kickoff - discussed timeline and milestones",
  metadata: {
    category: "meeting",
    importance: "medium",
    tags: ["project-alpha", "planning"]
  }
});

Note-specific metadata:

category - Note classification (reference, observation, meeting, learning, personal)
importance - Note priority (high, medium, low)
tags - Categorization tags

Ideas

Ideas capture concepts, plans, and creative thoughts with feasibility tracking.

await mirra.memory.create({
  type: "idea",
  content: "Build a mobile app for tracking daily habits",
  metadata: {
    idea_type: "business",
    feasibility: "medium",
    development_effort: "month_project"
  }
});

Idea-specific metadata:

idea_type - Category (business, creative, technical, personal, improvement)
feasibility - Viability assessment (high, medium, low, research_needed)
development_effort - Estimated work (weekend_project, month_project, major_undertaking)

Shopping Items

Shopping items manage shopping lists with store preferences and priorities.

await mirra.memory.create({
  type: "shopping_item",
  content: "Organic milk",
  metadata: {
    priority: "medium",
    store_preference: "Whole Foods",
    category: "dairy"
  }
});

Shopping item metadata:

priority - Purchase urgency (low, medium, high)
store_preference - Preferred retailer
category - Product category
status - Purchase state (open, purchased, cancelled)

Topics

Topics represent general knowledge, concepts, and subjects for semantic linking.

await mirra.memory.create({
  type: "topic",
  content: "Machine Learning",
  metadata: {
    description: "AI subfield focused on algorithms that improve through experience",
    tags: ["technology", "ai"]
  }
});

Contacts

Contacts store information about people, including relationships and context.

await mirra.memory.create({
  type: "contact",
  content: "John Smith",
  metadata: {
    email: "john.smith@example.com",
    organization: "Acme Corp",
    relationship: "colleague"
  }
});

Search Capabilities

The memory adapter provides three complementary search methods:

Semantic Search

Semantic search uses vector embeddings to find conceptually similar memories, even when exact keywords don't match.

const results = await mirra.memory.search({
  query: "upcoming tasks",
  limit: 10
});

Returns memories ranked by semantic similarity score (0.0 to 1.0).

Query (Filtered Search)

Query enables precise filtering by type, status, metadata fields, and graph context.

const results = await mirra.memory.query({
  type: "task",
  filters: {
    status: "open",
    priority: "high"
  },
  limit: 20,
  offset: 0
});

Supports pagination and complex filtering logic.

Find One

Find a specific entity by ID or unique criteria.

const task = await mirra.memory.findOne({
  filters: { id: "task_abc123" }
});

Graph-Based Access Control

All memory operations respect graph-based permissions. Memories are associated with a graph ID that determines who can access them:

Personal Graph (user:{userId}) - Private memories accessible only by the owner
Group Graphs (group:{groupId}) - Shared memories accessible to group members
Contact Graphs (user_contact:{contactId}) - Memories shared in direct conversations

By default, memories are created in your personal graph. The graph ID is automatically determined from the service context (authenticated user, delegated visitor, or service account).

Memory Operations

The memory adapter provides comprehensive CRUD operations:

Create - Add new memory entities to the knowledge graph
Search - Semantic search across all memory types
Query - Filtered search with pagination and type filtering
Find One - Retrieve a specific entity by ID or criteria
Update - Modify existing memory content and metadata
Delete - Remove memory entities from the graph
Upload Document - Add documents with automatic chunking and embedding
Search Documents - Semantic search across document chunks
Get Document Chunks - Retrieve document chunks for a specific document
Get Document Status - Check document processing status

Aggregation Operations

The memory adapter implements aggregation operations for analytics and reporting:

Get Task Completion

Returns task completion statistics over a time range:

const stats = await mirra.memory.getTaskCompletion({
  startDate: "2024-01-01",
  endDate: "2024-01-31"
});

Get Upcoming Reminders

Returns upcoming tasks and deadlines:

const reminders = await mirra.memory.getUpcomingReminders({
  daysAhead: 7
});

Get Memory Stats

Returns general statistics about stored memories:

const stats = await mirra.memory.getMemoryStats();

Next Steps

Operations - Complete API reference for all memory operations
Examples - Practical code examples and patterns
Technical Notes - Graph structure, embeddings, and best practices