🧠 Memory Graph MCP Server

🚀 A blazing-fast Knowledge Graph server for AI Agents

Give your AI perfect memory. Forever.

Features • Quick Start • API Reference • Architecture

---

⚠️ DISCLAIMER: ALL SOURCE CODE IS AI-GENERATED. THE AUTHOR ASSUMES NO LIABILITY FOR PATENT, INTELLECTUAL PROPERTY, OR LEGAL COMPLIANCE ISSUES IN ANY JURISDICTION.

---

🎯 The Problem

AI Agents forget everything between sessions. They hallucinate facts. They lose context.

Memory Graph fixes this.

Before: "Sorry, I don't have information about your project structure..."
After:  "Based on your Auth Module which implements JWT, I suggest..."

---

✨ Features

🛠️ 15 Powerful Tools

Category	Tools	Description
Memory	create_entities, create_relations, add_observations, delete_entities, delete_observations, delete_relations, read_graph, search_nodes, open_nodes	Full CRUD for knowledge graph
Query	get_related, traverse, summarize	Advanced graph traversal
Temporal	get_relations_at_time, get_relation_history	Time-travel queries
Utility	get_current_time	Timestamp helper

🔥 Why Memory Graph?

Feature	Description
⚡ Blazing Fast	In-memory cache with file persistence. Nanosecond reads.
🔒 Thread-Safe	Production-ready with Mutex-based concurrency control
🔍 Semantic Search	Built-in synonym matching (developer ↔ coder ↔ engineer)
⏰ Time Travel	Query historical state with validFrom/validTo
📏 Pagination	Handle massive graphs with limit/offset
✅ Type Validation	Soft warnings for non-standard types
🦀 Pure Rust	Single binary, ~3MB. Only depends on serde

---

🚀 Quick Start

Option 1: Build from Source

git clone https://github.com/maithanhduyan/memory-graph.git
cd memory-graph
cargo build --release

Option 2: Docker

docker run -v $(pwd)/data:/data ghcr.io/maithanhduyan/memory-graph

Configure VS Code

Create .vscode/mcp.json:

{
    "servers": {
        "memory": {
            "type": "stdio",
            "command": "${workspaceFolder}/target/release/memory-server.exe",
            "env": {
                "MEMORY_FILE_PATH": "${workspaceFolder}/memory.jsonl"
            }
        }
    }
}

Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "/path/to/memory-server",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.jsonl"
      }
    }
  }
}

---

📖 API Reference

Memory Tools

create_entities

{
  "entities": [{
    "name": "Auth Module",
    "entityType": "Module",
    "observations": ["Implements JWT", "Uses bcrypt"]
  }]
}

create_relations

{
  "relations": [{
    "from": "Auth Module",
    "to": "User Service",
    "relationType": "depends_on"
  }]
}

search_nodes (with Semantic Search)

{
  "query": "developer",  // Also matches: coder, programmer, engineer
  "limit": 10,
  "includeRelations": true
}

read_graph (with Pagination)

{
  "limit": 50,
  "offset": 0
}

Temporal Queries

get_relations_at_time

{
  "timestamp": 1704067200,
  "entityName": "Alice"
}
// Returns: Relations valid at that specific point in time

get_relation_history

{
  "entityName": "Alice"
}
// Returns: All relations (current + expired) with isCurrent flag

Graph Traversal

traverse

{
  "startNode": "Project: MyApp",
  "path": [
    {"relationType": "contains", "direction": "out"},
    {"relationType": "implements", "direction": "out", "targetType": "Feature"}
  ],
  "maxResults": 50
}

get_related

{
  "entityName": "Auth Module",
  "direction": "both",
  "relationType": "depends_on"
}

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AI Agent (Claude, etc.)                  │
└─────────────────────────────────────────────────────────────┘
                              │ JSON-RPC 2.0 (stdio)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Memory Graph MCP Server                    │
│  ┌───────────────────────────────────────────────────────┐ │
│  │                  MCP Protocol Layer                    │ │
│  │          (initialize, tools/list, tools/call)         │ │
│  └───────────────────────────────────────────────────────┘ │
│                              │                              │
│  ┌───────────────────────────────────────────────────────┐ │
│  │                    Tool Registry                       │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │ │
│  │  │ Memory   │  │  Query   │  │ Temporal │            │ │
│  │  │ Tools(9) │  │ Tools(3) │  │ Tools(2) │            │ │
│  │  └──────────┘  └──────────┘  └──────────┘            │ │
│  └───────────────────────────────────────────────────────┘ │
│                              │                              │
│  ┌───────────────────────────────────────────────────────┐ │
│  │            KnowledgeBase (Thread-Safe)                 │ │
│  │  ┌─────────────────────┐  ┌─────────────────────────┐ │ │
│  │  │  Mutex<Graph>       │  │   Synonym Dictionary    │ │ │
│  │  │  (In-Memory Cache)  │  │   (Semantic Search)     │ │ │
│  │  └─────────────────────┘  └─────────────────────────┘ │ │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                   ┌────────────────────┐
                   │   memory.jsonl     │
                   │  (JSONL Storage)   │
                   └────────────────────┘

Data Model

Entity:

{
  "name": "Auth Module",
  "entityType": "Module",
  "observations": ["Implements JWT", "Uses bcrypt"],
  "createdAt": 1704067200,
  "updatedAt": 1704153600
}

Relation (with Temporal Support):

{
  "from": "Alice",
  "to": "NYC",
  "relationType": "lives_in",
  "createdAt": 1704067200,
  "validFrom": 1704067200,
  "validTo": 1735689599
}

---

📊 Standard Types

Entity Types (11)

Project Module Feature Bug Decision Requirement Milestone Risk Convention Schema Person

Relation Types (12)

contains implements fixes caused_by depends_on blocked_by assigned_to part_of relates_to supersedes affects requires

⚠️ Custom types are allowed with soft warnings.

---

🧪 Testing

cargo test

# Output:
# test tests::test_create_entities ... ok
# test tests::test_create_relations ... ok
# test tests::test_search_nodes ... ok
# test tests::test_delete_entities ... ok
# test tests::test_concurrent_access ... ok      # 10 threads
# test tests::test_concurrent_read_write ... ok  # 5 readers + 3 writers
#
# test result: ok. 6 passed; 0 failed

---

🔧 Configuration

Environment Variable	Default	Description
MEMORY_FILE_PATH	./memory.jsonl	Path to knowledge graph storage

---

🗺️ Roadmap

• Core CRUD operations (9 tools)
• Advanced query tools (3 tools)
• Semantic search with synonyms
• Temporal relations (time-travel)
• Pagination support
• Thread-safe in-memory cache
• Type validation with warnings
• Vector embeddings for true semantic search
• Web UI for graph visualization
• Multi-tenant support
• WAL (Write-Ahead Log) for large graphs

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

# Fork the repo, then:
git checkout -b feature/amazing-feature
cargo test
git commit -m "Add amazing feature"
git push origin feature/amazing-feature
# Open a Pull Request

---

📄 License

MIT License - see LICENSE for details.

---

Built with 🦀 Rust and ❤️ for AI Agents

If this project helps you, please ⭐ star the repo!

Report Bug · Request Feature