agent-memory-mcp

Agent Memory MCP Server

A Model Context Protocol (MCP) server that provides persistent memory capabilities for AI agents. Store, query, and manage memories across sessions with support for tags, metadata, keyword-based semantic search, TTL expiration, memory linking, and batch operations.

Features

• Persistent Storage: Memories are saved to disk and persist across server restarts
• Keyword Search: Find relevant memories using keyword-based semantic matching
• Tag Support: Organize memories with tags for easy filtering
• Metadata: Attach custom metadata to memories
• Memory Updates: Update existing memories without creating duplicates
• Batch Operations: Efficiently store or delete multiple memories at once
• TTL Support: Set expiration times for memories with automatic cleanup
• Memory Linking: Create relationships between memories to build knowledge graphs
• Import/Export: Backup and migrate memories between systems
• Statistics: View memory usage patterns and storage metrics
• MCP Compatible: Works with Claude Desktop, Cursor, Windsurf, Kiro, and other MCP clients

Installation

From npm (recommended)

npm install -g agent-memory-mcp

From source

git clone <repository-url>
cd agent-memory-mcp
npm install
npm run build

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "agent-memory": {
      "command": "agent-memory-mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory-mcp"]
    }
  }
}

Windsurf

Add to your Windsurf configuration:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory-mcp"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory-mcp"]
    }
  }
}

Available Tools

Core Tools

memory_store

Store a new memory entry with optional TTL.

Parameters:

• content (string, required): The memory content to store
• tags (string[], optional): Tags for categorization
• metadata (object, optional): Custom metadata
• ttl (object, optional): Time-to-live for automatic expiration
  • value (number): Numeric value
  • unit (string): One of "seconds", "minutes", "hours", "days"

Example:

{
  "content": "User prefers dark mode and uses TypeScript",
  "tags": ["preferences", "coding"],
  "metadata": { "priority": "high" },
  "ttl": { "value": 7, "unit": "days" }
}

memory_query

Search memories using keyword-based semantic matching.

Parameters:

• query (string, required): Search query
• k (number, optional): Maximum results to return (default: 10)
• tags (string[], optional): Filter by tags

Example:

{
  "query": "user preferences",
  "k": 5,
  "tags": ["preferences"]
}

memory_list

List all stored memories with pagination.

Parameters:

• limit (number, optional): Maximum entries to return
• offset (number, optional): Number of entries to skip
• includeExpired (boolean, optional): Include expired memories (default: false)

Example:

{
  "limit": 20,
  "offset": 0,
  "includeExpired": false
}

memory_delete

Delete a specific memory by ID.

Parameters:

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

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

memory_clear

Clear all memories from the store.

Parameters:

• confirm (boolean, optional): Must be true to confirm deletion

Example:

{
  "confirm": true
}

Update Tool

memory_update

Update an existing memory's content, tags, or metadata.

Parameters:

• id (string, required): Memory ID to update
• content (string, optional): New content (replaces existing)
• tags (string[], optional): New tags (replaces existing)
• metadata (object, optional): New metadata (merges with existing)

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "Updated user preferences",
  "tags": ["preferences", "updated"],
  "metadata": { "lastReviewed": "2024-01-15" }
}

Batch Operations

memory_batch_store

Store multiple memories in a single atomic operation.

Parameters:

• items (array, required): Array of memory items (max 100)
  • content (string, required): Memory content
  • tags (string[], optional): Tags
  • metadata (object, optional): Metadata
  • ttl (object, optional): TTL configuration

Example:

{
  "items": [
    { "content": "First memory", "tags": ["batch"] },
    { "content": "Second memory", "tags": ["batch"], "ttl": { "value": 1, "unit": "hours" } }
  ]
}

Response:

{
  "success": true,
  "total": 2,
  "succeeded": 2,
  "failed": 0,
  "results": [
    { "index": 0, "success": true, "id": "uuid-1" },
    { "index": 1, "success": true, "id": "uuid-2" }
  ]
}

memory_batch_delete

Delete multiple memories in a single atomic operation.

Parameters:

• ids (string[], required): Array of memory IDs to delete (max 100)

Example:

{
  "ids": ["uuid-1", "uuid-2", "uuid-3"]
}

Statistics & Cleanup

memory_stats

Get statistics about stored memories.

Parameters: None

Response:

{
  "totalCount": 150,
  "tagCounts": { "preferences": 25, "coding": 45 },
  "storageSizeBytes": 102400,
  "dateRange": {
    "oldest": "2024-01-01T00:00:00.000Z",
    "newest": "2024-01-15T12:30:00.000Z"
  },
  "averageContentLength": 256,
  "expiredCount": 5,
  "linkCount": 12
}

memory_cleanup

Remove all expired memories from storage.

Parameters: None

Response:

{
  "deletedCount": 5,
  "deletedIds": ["uuid-1", "uuid-2", "uuid-3", "uuid-4", "uuid-5"]
}

Memory Linking

memory_link

Create a bidirectional link between two memories.

Parameters:

• sourceId (string, required): Source memory ID
• targetId (string, required): Target memory ID
• linkType (string, optional): Type of relationship (default: "related")
  • Predefined types: "related", "contradicts", "extends", "supersedes"
  • Custom types are also supported

Example:

{
  "sourceId": "uuid-1",
  "targetId": "uuid-2",
  "linkType": "extends"
}

memory_get_links

Get all links associated with a memory.

Parameters:

• id (string, required): Memory ID

Response:

{
  "links": [
    {
      "sourceId": "uuid-1",
      "targetId": "uuid-2",
      "linkType": "extends",
      "createdAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Import/Export

memory_export

Export memories to JSON format for backup or migration.

Parameters:

• tags (string[], optional): Only export memories with these tags
• includeExpired (boolean, optional): Include expired memories (default: false)

Example:

{
  "tags": ["important"],
  "includeExpired": false
}

Response:

{
  "version": "1.0",
  "exportedAt": "2024-01-15T12:00:00.000Z",
  "memories": [...],
  "links": [...]
}

memory_import

Import memories from a previously exported JSON file.

Parameters:

• data (object, required): Export data object
  • memories (array, required): Array of memory entries
  • links (array, optional): Array of memory links

Example:

{
  "data": {
    "memories": [
      {
        "id": "old-uuid",
        "content": "Imported memory",
        "tags": ["imported"],
        "metadata": {},
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "links": []
  }
}

Response:

{
  "success": true,
  "memoriesImported": 1,
  "linksImported": 0,
  "idMappings": { "old-uuid": "new-uuid" },
  "errors": []
}

TTL (Time-to-Live) Feature

The TTL feature allows you to set expiration times for memories. Expired memories are automatically excluded from queries and listings.

Supported TTL Units

• seconds: Expire after N seconds
• minutes: Expire after N minutes
• hours: Expire after N hours
• days: Expire after N days

Usage Examples

// Store a memory that expires in 1 hour
{
  "content": "Temporary note",
  "ttl": { "value": 1, "unit": "hours" }
}

// Store a memory that expires in 7 days
{
  "content": "Weekly reminder",
  "ttl": { "value": 7, "unit": "days" }
}

Cleanup

Use memory_cleanup to permanently delete all expired memories:

// Returns: { "deletedCount": 5, "deletedIds": [...] }

Memory Linking Feature

Build knowledge graphs by creating relationships between memories.

Link Types

• related: General relationship (default)
• contradicts: Memories that conflict with each other
• extends: Memory that adds to another
• supersedes: Memory that replaces another
• Custom types are also supported

Usage Example

// Create a link
{
  "sourceId": "memory-about-topic",
  "targetId": "related-memory",
  "linkType": "extends"
}

// Links are bidirectional - both memories will show the link

Cascade Delete

When a memory is deleted, all its associated links are automatically removed.

Data Storage

Memories are stored in JSON format at:

• macOS/Linux: ~/.agent-memory/memories.json
• Windows: %USERPROFILE%\.agent-memory\memories.json

Storage Format

{
  "memories": [
    {
      "id": "uuid",
      "content": "...",
      "tags": [],
      "metadata": {},
      "createdAt": "...",
      "updatedAt": "...",
      "expiresAt": "..."
    }
  ],
  "links": [
    {
      "sourceId": "uuid1",
      "targetId": "uuid2",
      "linkType": "related",
      "createdAt": "..."
    }
  ]
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

License

MIT