Memory MCP — Graph-Based Memory & Persona Management

[!IMPORTANT] Dependency Warning: This skill requires the memory MCP server to be running and registered with the Model Context Protocol (MCP) host. It enables persistent memory, knowledge graph entities, context tracking, and cross-session intelligence.

This skill equips the agent to store, search, and manage memories across sessions; track entities and relationships in a knowledge graph; maintain user persona, mood, and learning patterns; and surface proactive suggestions based on memory health.

Guidelines for the Agent

1. Tool Architecture — 9 Consolidated Tools

The memory MCP exposes 9 tools, each with an op (operation) parameter:

2. Common Parameters

Every tool call requires:

• userId (required) — Who owns this data. Always pass the user identifier.
• op (required) — Which operation to perform on the tool.

Each tool also accepts optional context parameters:

• projectId — Scope to a project
• sessionId — Conversation thread identifier

3. Core Memory Operations (memory__memory)

Store a Memory

{ "op": "remember", "userId": "u1", "userMessage": "Fixed @AuthService bug!", "agentMessage": "Great work!" }

Auto-features: intent detection, entity extraction (@mentions, CamelCase, URLs), auto-linking.

Search / Recall

{ "op": "recall", "userId": "u1", "query": "auth bug" }
{ "op": "search", "userId": "u1", "query": "database config" }

Context for LLM

{ "op": "context", "userId": "u1", "sessionId": "sess_123", "maxTokens": 2000 }

Memory Health & Maintenance

{ "op": "health", "userId": "u1" }
{ "op": "decay", "userId": "u1", "daysUnused": 7 }
{ "op": "dedup", "userId": "u1", "threshold": 0.8, "autoMerge": false }

Smart Features

{ "op": "suggest", "userId": "u1" }
{ "op": "remind", "userId": "u1", "reminderType": "followup", "title": "Check database", "priority": 8 }
{ "op": "mood", "userId": "u1", "mood": "excited", "intensity": 8, "context": "Launch day!" }
{ "op": "persona", "userId": "u1", "traits": {"creative": true}, "style": "friendly" }
{ "op": "learn", "userId": "u1", "type": "work", "pattern": "prefers morning" }

Snippet Search (Exact & Semantic with context)

{
  "op": "snippet_search",
  "userId": "u1",
  "text": "Line 1: system boot\nLine 2: loading config...",
  "query": "system boot",
  "searchType": "exact",
  "beforeLimit": 1,
  "afterLimit": 1
}

Supports exact/semantic matches, parameter clamping, whitespace collapsing, and SQL wildcard escaping in database fallback.

Unified Contact CRUD

{ "op": "contact", "contactOp": "create", "userId": "u1", "name": "vk", "role": "founder", "properties": {"status": "active"} }
{ "op": "contact", "contactOp": "get", "userId": "u1", "name": "VK" }

Standardizes contact management with space-collapsed names, case-insensitive retrievals, and properties sanitization.

Unified Contact Graph & Path Traversal

{ "op": "contact_graph", "graphOp": "link", "userId": "u1", "fromId": "vk", "toId": "nandini", "relationType": "wife" }
{ "op": "contact_graph", "graphOp": "path", "userId": "u1", "fromId": "vk", "toId": "vk", "depth": 3 }

Manages relationships with lowercase-normalized edge types, per-path visited tracking, and loop/cycle discovery.

4. Knowledge Graph (entity + relation)

Create Entity

{ "op": "create", "userId": "u1", "entityType": "Person", "name": "Alice", "properties": {"role": "Engineer"} }

Search Entities

{ "op": "search", "userId": "u1", "entityType": "Person", "search": "alice" }

Create Relation

{ "op": "create", "userId": "u1", "fromId": "e1", "toId": "e2", "type": "WORKS_WITH" }

5. Short-Term KV Storage (memory__short_term)

Fast key-value store for session data. Cleared periodically.

{ "op": "set", "userId": "u1", "key": "active_task", "value": {"id": "t1"} }
{ "op": "get", "userId": "u1", "key": "active_task" }
{ "op": "list", "userId": "u1" }

6. Project & Task Management (memory__project)

{ "op": "create_project", "userId": "u1", "name": "My App", "description": "A new app" }
{ "op": "plan_task", "userId": "u1", "projectId": "p1", "title": "Fix bug", "status": "pending" }
{ "op": "list_tasks", "userId": "u1", "projectId": "p1" }
{ "op": "complete_task", "id": "task_123" }

7. Context Tracking (memory__context)

{ "op": "better", "userId": "u1", "timeRange": "week" }
{ "op": "chat_add", "userId": "u1", "role": "user", "content": "Hello" }
{ "op": "chat_get", "userId": "u1", "limit": 10 }

8. Extract & Remember (memory__extract)

{ "op": "entities", "userId": "u1", "text": "John from Acme called" }
{ "op": "learning", "userId": "u1", "insight": "Tests first" }
{ "op": "discovery", "userId": "u1", "content": "Found new approach" }
{ "op": "mistake", "userId": "u1", "description": "Used wrong API", "resolution": "Update docs" }

9. Share (memory__share)

{ "op": "share", "userId": "u1", "toOwnerId": "u2", "content": "Deadline Sunday" }
{ "op": "shared_with_me", "userId": "u1" }

10. 8-Phase Auto-Linking System

Memories are automatically linked across sessions using:

Features: bidirectional links, max 15 links per memory, adaptive boost for high-priority items.

11. Intent Detection (Auto)

The system auto-detects intent when storing memories:

12. Session Workflow

At session start:

// Get recent context
{ "op": "better", "userId": "u1", "timeRange": "week" }

// Check pending reminders
{ "op": "remind", "userId": "u1" }

// Get health overview
{ "op": "health", "userId": "u1" }

During session:

// Store conversation
{ "op": "remember", "userId": "u1", "userMessage": "...", "agentMessage": "..." }

// Extract entities
{ "op": "entities", "userId": "u1", "text": "..." }

// Track mood
{ "op": "mood", "userId": "u1", "mood": "happy", "context": "..." }

At session end:

// Store summary
{ "op": "chat_summary", "userId": "u1", "summary": "..." }

// Clean up short-term
{ "op": "cleanup", "userId": "u1" }

13. Error Handling

14. Best Practices

1. Always pass userId — Every tool call requires it.
2. Use entity extraction — Extract entities from user messages to build the knowledge graph.
3. Track mood — Call mood during emotionally significant moments.
4. Remember at end — Store session summaries for cross-session continuity.
5. Use context before starting — better op gives you full context before you begin.
6. Health check periodically — Run health + decay to keep memory clean.