🧠 MemoryX MCP Server

Give your AI assistants long-term memory via Model Context Protocol.

MemoryX MCP Server enables Cursor, VS Code, Claude Desktop, and other MCP clients to store and retrieve memories across conversations.

✨ Features

• 🚀 Zero Config - Auto-registers on first use, no API key needed
• 🔍 save_memory - Store important information with automatic categorization
• 🔎 search_memory - Semantic search + graph-related memories (optional entity_name for graph expansion)
• 🕸️ search_memory_graph - Search by graph entity (file path, class name, method, etc.)
• 📋 list_memory - List recent memories in chronological order
• 🗑️ delete_memory - Remove outdated or incorrect memories
• ℹ️ get_account_info - Check connection status and agent info
• 📝 Prompts - Pre-built templates for common workflows

🚀 Quick Start

Install

npm install -g @t0ken.ai/memoryx-mcp-server

Configure Cursor / VS Code

Add to ~/.cursor/mcp.json or VS Code MCP config:

{
  "mcpServers": {
    "memoryx": {
      "command": "memoryx-mcp-server"
    }
  }
}

That's it! The server auto-registers on first use - no additional configuration needed.

Cursor: No Manual Rules Needed

When you use MemoryX MCP in Cursor:

• Plugin (recommended): Install the MemoryX Cursor plugin for rules and hooks. No manual setup.
• MCP only: Add the MCP server for tools. The server does not write .cursor/rules or .cursor/hooks.json. To use hooks (e.g. session-start, pre-compact, post-tool-use), add .cursor/hooks.json yourself (see plugin’s hooks/hooks.json) or copy from the plugin repo.
• Reload the Cursor window after changing MCP config or hooks.

Configure Your Agent (System Prompt / Rules) — Non-Cursor

The MCP server only provides the tools; the AI will not automatically know when or how to save memory. For Cursor, rules and hooks are installed automatically (see above). For VS Code, Claude Desktop, or other MCP hosts, you must put the following constraints into your AI's system prompt or rules (e.g. VS Code rules, Claude's custom instructions) so the agent is instructed to call save_memory at the right times.

Where to add:

• Cursor: Use the MemoryX Cursor plugin for rules and hooks, or copy rules from the plugin into .cursor/rules/.
• VS Code / other MCP hosts: system prompt or instructions in settings
• Claude Desktop: Custom instructions / system prompt in config

Suggested rule: “MemoryX Auto-Memory Rules”

# MemoryX Auto-Memory Rules

## Task Completion Flow
1. Complete task code changes
2. **MUST** call `save_memory` tool to save task summary
3. **THEN** call `attempt_completion` (or your completion flow) to report

## save_memory Content Requirements
- What task was completed
- Which files were modified
- Important design decisions or lessons learned
- Next steps (if any)

## When to Save (Triggers)
- **Task completion** – Summarize and save before marking done
- **Important design decisions** – Architecture, tech choices, API/schema changes
- **User requests** – "remember", "don't forget", "note this"
- **User preferences** – "I like", "I hate", "I usually..."
- **Cross-session info** – Anything that should persist to the next session
- **End of conversation** – Optional: add a rule like “At end of long sessions, call save_memory with a short summary of key points”

## Timed / Scheduled Saving
If you want the agent to save memory on a schedule (e.g. every N messages or at idle), add to your system prompt or rules, for example:
- “After every 10 user messages, call save_memory with a 1–2 sentence summary of the current topic if it’s substantive.”
- “When the user has not sent a message for 5 minutes and the conversation had substance, offer to save a brief summary via save_memory.”

## How to Save
- Call the **save_memory** tool with:
  - **content**: One atomic fact or short summary (self-contained; use absolute dates like YYYY-MM-DD; avoid “it”/“this”—use explicit referents).
  - **metadata** (optional): `category` (semantic | episodic | procedural | emotional | reflective), `tags` (string array).
- One fact per call; for multiple points, call save_memory once per fact.

Copy or adapt the above into your rules so the agent consistently saves memory at the right moments.

Configure Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memoryx": {
      "command": "memoryx-mcp-server"
    }
  }
}

📖 Tools

save_memory

Save information to long-term memory. Important: The agent will not call this automatically—put the MemoryX Auto-Memory Rules (when to save, task flow, content requirements) into your system prompt or rules so the agent is constrained to use it.

⚡ AUTO-SAVE TRIGGERS - Always call save_memory when:

1. Important Design Decisions → Save immediately

   • Architecture choices, technology selections
   • File structure decisions, naming conventions
   • API design, database schema changes

2. Task Completion → Summarize and save

   • What was accomplished
   • Key changes made
   • Important learnings or gotchas discovered

3. Cross-Session Needs → Use new_task to pass context, then save

   • Information needed in future sessions
   • Ongoing project state
   • Pending tasks and next steps

4. User Explicitly Requests → Save immediately

   • "remember", "note this", "don't forget"
   • User corrects your error (store correct version)
   • User expresses preferences (I like/hate/usually...)

5. End of Conversation → Generate summary

   • Create a 100-word summary of key points
   • Save important decisions and outcomes

Categories (use in metadata.category):

• semantic - facts, knowledge, user preferences
• episodic - specific events, experiences
• procedural - skills, methods, how-to steps
• emotional - feelings, emotional states
• reflective - insights, patterns, lessons learned

Example:

{
  "content": "User prefers dark theme in VS Code",
  "metadata": {
    "category": "semantic",
    "tags": ["preference", "editor"]
  }
}

search_memory

Search historical memories before responding.

Always call BEFORE:

• Answering questions about user preferences/history
• Topics that might relate to past conversations
• Any personalized response needed

Workflow: search → review results → generate informed response

list_memory

List recent memories in chronological order (newest first).

Use when:

• Reviewing what has been stored
• Getting context at the start of a conversation
• Finding specific memories when unsure of keywords

Parameters:

• limit - Number of memories to return (default: 20)

delete_memory

Delete a specific memory by ID.

Use when:

• User explicitly asks to forget something
• You find outdated or incorrect information

Parameters:

• memory_id - The ID of the memory to delete (from list_memory or search_memory)

get_account_info

Get current connection status including:

• API Key (masked)
• Agent ID
• Queue length

📝 Prompts

Pre-built templates for common memory workflows:

| Prompt | Description | Use Case | |--------|-------------|----------| | start-with-memory | Retrieve recent memories | Beginning of a new session | | archive-session | Extract and save key points | End of a conversation | | recall-context | Recall context from memory | Before responding to questions |

start-with-memory

Use at the start of a new conversation to restore context:

As my personal assistant at the start of a new conversation, 
please first read the memoryx://memories/recent resource to retrieve my recent memories. 
Based on retrieved information, briefly summarize what we've been working on 
and ask about my next plans.

archive-session

Use at the end of a conversation to save important points:

Please review this conversation about {topic}. Extract:
1. Key decisions made
2. TODO items and action items
3. Important facts mentioned by user
Use save_memory tool to store these in structured format.

recall-context

Recall relevant context before responding:

Please recall relevant context from memory about: "{topic}". 
Call search_memory to retrieve related historical discussions, 
then use that context to inform your response.

🔗 Resources

MCP Resources for direct access to memory data:

| Resource | Description | |----------|-------------| | memoryx://status | Connection status and queue info | | memoryx://memories/recent | Recent 20 memories in chronological order |

LLM can read these resources directly via MCP's ReadResource API to get context without calling tools.

📁 Local Storage

Data stored in ~/.memoryx/sdk/ (managed by SDK):

• memoryx.db - SQLite database with agent info, queue, and cached data

🔄 MCP Mode vs OpenClaw Mode

| Feature | MCP Server | OpenClaw Plugin | |---------|------------|-----------------| | Data Source | LLM summarized single additions | Bidirectional conversation flow | | Server Processing | Direct entity extraction | LLM summarization then extraction | | Trigger | 20k tokens / 1 min idle | 30k tokens / 5 min idle | | Use Case | Cursor/Claude Desktop | OpenClaw Gateway |

📚 More Resources

• MemoryX Platform
• Documentation
• Node.js SDK
• Python SDK
• GitHub

📄 License

MIT © MemoryX Team