Memory MCP Server - Knowledge Graph

Persistent memory and knowledge graph for AI agents. Store entities, relations, and observations that persist across sessions.

Features

• Entities - Store named nodes with types and observations
• Relations - Connect entities with directional relationships
• Observations - Attach discrete facts to entities
• Search - Find entities by name, type, or observation content
• Persistence - Memory persists in Apify Key-Value Store
• Multi-tenant - Separate memory spaces using memoryKey

Tools

Tool	Description
memory.create_entities	Create new entities in the graph
memory.create_relations	Create relations between entities
memory.add_observations	Add facts to existing entities
memory.delete_entities	Remove entities (cascades relations)
memory.delete_observations	Remove specific observations
memory.delete_relations	Remove specific relations
memory.read_graph	Get complete graph with all data
memory.search_nodes	Search entities by query
memory.open_nodes	Get specific entities by name

Data Model

Entity

{
  "name": "John Doe",
  "entityType": "person",
  "observations": [
    "Works at Acme Corp",
    "Lives in New York",
    "Prefers email communication"
  ]
}

Relation

{
  "from": "John Doe",
  "to": "Acme Corp",
  "relationType": "works_at"
}

Examples

Create Entities

{
  "tool": "memory.create_entities",
  "memoryKey": "my-project",
  "entities": "[{\"name\": \"Alice\", \"entityType\": \"person\", \"observations\": [\"Team lead\", \"Prefers Slack\"]}]"
}

Create Relations

{
  "tool": "memory.create_relations",
  "memoryKey": "my-project",
  "relations": "[{\"from\": \"Alice\", \"to\": \"Engineering Team\", \"relationType\": \"leads\"}]"
}

Add Observations

{
  "tool": "memory.add_observations",
  "memoryKey": "my-project",
  "entityName": "Alice",
  "observations": "[\"Recently promoted\", \"Working on Q4 roadmap\"]"
}

Search Nodes

{
  "tool": "memory.search_nodes",
  "memoryKey": "my-project",
  "searchQuery": "engineering"
}

Read Full Graph

{
  "tool": "memory.read_graph",
  "memoryKey": "my-project"
}

Output

When run as an Apify Actor (one tool call per run), results are also pushed to the run's default dataset. Records carry a type field:

Record type	When	Key fields
server_info	Every run (first record)	version, tools, memoryKey, initialStats
graph_state	When no tool is supplied	entities, relations, timestamp
tool_result	After a tool runs	tool, status, saved, tool-specific result, finalStats
error	Invalid tool or internal error	status, errors

The full knowledge graph is persisted separately to the Apify Key-Value Store under memory_{memoryKey}. When run through Apify's MCP gateway, the same operations are returned directly as MCP tool responses.

Use Cases

• Personal Assistant Memory - Remember user preferences, contacts, projects
• CRM Knowledge Base - Store customer information and relationships
• Project Context - Track team members, decisions, and dependencies
• Research Notes - Connect concepts, papers, and findings
• Conversation History - Persist important facts across chat sessions

Memory Keys

Use memoryKey to create separate memory spaces:

• user-123 - Per-user memory
• project-alpha - Per-project memory
• session-xyz - Per-session memory

Memory persists in Apify Key-Value Store under key memory_{memoryKey}.

MCP Integration

Works with Claude Desktop, VS Code, and any MCP-compatible agent.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "url": "https://mcp.apify.com?actors=YOUR_USERNAME/memory-mcp-server"
    }
  }
}

System Prompt Example

Add to your AI agent's system prompt:

You have access to a persistent memory system. At the start of each conversation:
1. Use memory.read_graph to recall what you know about the user
2. As you learn new information, use memory.create_entities and memory.add_observations to save it
3. Use memory.create_relations to connect related concepts

Important information to remember:
- User's name, preferences, and goals
- Projects they're working on
- People and organizations they mention
- Decisions and agreements made

Pricing

Apify compute (and storage) costs only. No external API or API key is required.

Limitations

• One tool per run. As an Apify Actor (server/main.js, the Docker entrypoint), each run executes exactly one memory operation and then exits. It is not a long-lived server in this mode; state is carried between runs through the Key-Value Store, not held in process memory.
• Persistence is snapshot-based. The whole graph is stored as a single JSON record per memoryKey at memory_{memoryKey}. loadExisting and saveMemory (both default true) control loading and saving; with saveMemory set to false, changes are not persisted. Each run's tool_result includes a saved flag (and a saveWarning if persistence failed) so a Key-Value Store outage degrades gracefully instead of silently losing data.
• No concurrency control. There is no locking. Concurrent runs against the same memoryKey can overwrite one another (last write wins).
• No enforced quotas. Entity/relation/observation counts and sizes are bounded by the Apify Key-Value Store record size limit and the run's available memory, not by hard-coded limits in the code. Very large graphs may hit the store's record-size limit.
• Substring search only. memory.search_nodes performs case-insensitive substring matching over names, types, and observations. There is no fuzzy, semantic, or vector search.
• Local HTTP server is separate. server/index.js is a standalone Express server that persists to local JSON files under a data/ directory; it is not used by the Apify Actor run. Local Actor runs emulate storage under the storage/ directory.
• MCP transport requirements. MCP access is provided through Apify's MCP gateway (mcp.apify.com) and requires an MCP-compatible client plus an Apify token. This package does not ship a standalone stdio MCP binary.

Support

For issues or feature requests, open a ticket on the Issues tab.