Memory Tools

Tools for storing and retrieving persistent agent memory.

Overview

Agent memory allows AI agents to store context that persists across conversations. Use it to remember user preferences, learned information, and ongoing context.

memory_ingest

Store information in memory.

{
  "name": "memory_ingest",
  "arguments": {
    "workspaceId": "ws_123",
    "content": "User prefers formal documentation style with code examples",
    "metadata": {
      "source": "user_preference",
      "confidence": 0.9
    },
    "tags": ["preferences", "style", "documentation"]
  }
}

Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID
content	string	Yes	Content to store
metadata	object	No	Additional metadata
tags	string[]	No	Tags for categorization

memory_query

Query memory by semantic similarity.

{
  "name": "memory_query",
  "arguments": {
    "workspaceId": "ws_123",
    "query": "documentation style preferences",
    "limit": 5,
    "tags": ["preferences"]
  }
}

Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID
query	string	Yes	Search query
limit	number	No	Max results
tags	string[]	No	Filter by tags

Response

{
  "results": [
    {
      "id": "mem_123",
      "content": "User prefers formal documentation style with code examples",
      "score": 0.92,
      "tags": ["preferences", "style"],
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

memory_daily

Get daily memory summary.

{
  "name": "memory_daily",
  "arguments": {
    "workspaceId": "ws_123",
    "date": "2025-01-22"
  }
}

Returns memories ingested on a specific date.

memory_days

List days with memory entries.

{
  "name": "memory_days",
  "arguments": {
    "workspaceId": "ws_123",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31"
  }
}

Response

{
  "days": [
    { "date": "2025-01-15", "count": 5 },
    { "date": "2025-01-18", "count": 3 },
    { "date": "2025-01-22", "count": 8 }
  ]
}

Use Cases

Remember User Preferences

// When user expresses a preference
await mcp.callTool('memory_ingest', {
  workspaceId: 'ws_123',
  content: 'User prefers bullet points over paragraphs',
  tags: ['preferences', 'formatting'],
});

// Later, when generating content
const prefs = await mcp.callTool('memory_query', {
  workspaceId: 'ws_123',
  query: 'formatting preferences',
  tags: ['preferences'],
});

Track Conversation Context

// Store important context from conversation
await mcp.callTool('memory_ingest', {
  workspaceId: 'ws_123',
  content: 'Currently working on Q1 roadmap project, focus on API improvements',
  tags: ['context', 'project'],
});

Learn from Corrections

// When user corrects the agent
await mcp.callTool('memory_ingest', {
  workspaceId: 'ws_123',
  content: 'The authentication API uses JWT, not sessions',
  tags: ['corrections', 'api', 'auth'],
});

memory_profile_distill

Generate or update a user's behavioral profile.

{
  "name": "memory_profile_distill",
  "arguments": {
    "workspaceId": "ws_123",
    "userId": "user_456",
    "spaceId": "space_789"
  }
}

Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID
userId	string	No	Target user (defaults to current)
spaceId	string	No	Scope to specific space

Response

{
  "profile": {
    "traits": {
      "focus": { "score": 7.2, "trend": "improving" },
      "execution": { "score": 8.1, "trend": "stable" },
      "creativity": { "score": 6.5, "trend": "improving" },
      "communication": { "score": 7.8, "trend": "stable" },
      "leadership": { "score": 5.9, "trend": "stable" },
      "learning": { "score": 8.4, "trend": "improving" },
      "resilience": { "score": 7.0, "trend": "stable" }
    },
    "patterns": {
      "completionRate": 0.82,
      "consistencyScore": 0.75,
      "diversityScore": 0.68,
      "collaborationScore": 0.71
    },
    "strengths": ["Strong execution", "Active learner"],
    "challenges": ["Could improve leadership initiative"],
    "recommendations": ["Try initiating a new project"]
  }
}

The profile system evaluates users across seven behavioral traits based on activity signals. See User Profiles for full documentation.

Architecture

Memory search uses pgvector with HNSW indexes for fast semantic similarity:

• Memory content is embedded using Gemini's text-embedding-004 model (768 dimensions)
• Queries are embedded and matched against stored memories using cosine similarity
• HNSW index provides O(log n) query performance
• Entity relationships are stored separately in Memgraph for graph traversals

This architecture separates concerns:

• pgvector handles semantic similarity (finding memories by meaning)
• Memgraph handles graph queries (finding related entities and traversals)

Best Practices

1. Use specific tags - Makes querying more effective
2. Include context - Store full context, not fragments
3. Tag sources - Know where memories came from
4. Clean periodically - Review and remove outdated memories
5. Be selective - Don't store everything, focus on valuable info