🧠 MemorizedMCP

A high-performance hybrid memory system for AI agents built on the Model Context Protocol (MCP). MemorizedMCP combines knowledge graphs, vector embeddings, full-text search, and documentary memory to provide intelligent, context-aware information storage and retrieval.

---

✨ Features

🗄️ Multi-Layer Memory Architecture

• STM (Short-Term Memory): Fast, ephemeral storage with automatic expiration
• LTM (Long-Term Memory): Persistent knowledge with importance-based retention
• Automatic Consolidation: Smart promotion from STM → LTM based on access patterns

🔗 Knowledge Graph (NEW!)

• Create and manage entities, documents, memories, and episodes
• Rich relationships with custom edge types (MENTIONS, EVIDENCE, RELATED)
• Tag-based organization and filtering
• Graph traversal and pattern discovery
• Full CRUD operations on nodes and edges

📚 Documentary Memory

• Ingest PDF, Markdown, and text documents
• Automatic chunking and embedding
• Entity extraction and linking
• Document versioning by path
• Cross-document relationship discovery

🔍 Hybrid Search

• Vector Search: Semantic similarity via embeddings
• Full-Text Search: BM25-style keyword matching (Tantivy + Sled)
• Graph Search: Entity-based traversal and relation queries
• Temporal Filters: Query by time ranges and episodes
• Query Caching: Sub-second responses for hot queries

⚡ Performance & Scalability

• Query percentiles tracking (p50, p95) for health monitoring
• Concurrent request handling with semaphore-based backpressure
• Incremental indexing and background maintenance
• Memory-mapped storage for efficient disk I/O

🛠️ Developer-Friendly

• MCP Protocol: Standard tools interface for AI agents
• HTTP API: RESTful endpoints for direct integration
• Backup/Restore: Snapshot-based data portability
• Validation Tools: Integrity checks and auto-repair

---

📋 Table of Contents

• Architecture
• Installation
• Quick Start
• Usage Examples
• API Documentation
• Configuration
• Development
• Contributing
• License

---

🏗️ Architecture

MemorizedMCP uses a fusion architecture that combines multiple indexing strategies:

┌─────────────────────────────────────────────────────────────┐
│                     MCP Protocol Layer                       │
│            (tools/call, tools/list, notifications)           │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   HTTP API & Router (Axum)                   │
└─────┬──────────┬──────────┬──────────┬──────────┬──────────┘
      │          │          │          │          │
┌─────▼────┐ ┌──▼───┐ ┌────▼────┐ ┌───▼────┐ ┌──▼──────┐
│ Vector   │ │ Text │ │ Graph   │ │Document│ │ System  │
│ Index    │ │Index │ │  (KG)   │ │ Store  │ │ Mgmt    │
│(HNSW ANN)│ │(BM25)│ │(Nodes+  │ │(Chunks)│ │(Backup) │
│          │ │      │ │ Edges)  │ │        │ │         │
└─────┬────┘ └──┬───┘ └────┬────┘ └───┬────┘ └──┬──────┘
      │         │          │          │         │
      └─────────┴──────────┴──────────┴─────────┘
                           │
                    ┌──────▼──────┐
                    │ Sled KV     │
                    │ (Embedded)  │
                    └─────────────┘

Storage Tiers:

• Hot: Query cache (in-memory, TTL-based)
• Warm: Primary KV store (Sled, memory-mapped)
• Cold: Archived snapshots (filesystem)
• Index: Tantivy full-text index (disk-backed)

---

🚀 Installation

Prerequisites

• Rust 1.75+ (for building from source)
• Windows 10+ ( Linux / macOS never tried )

Build from Source

git clone https://github.com/PerkyZZ999/MemorizedMCP.git
cd MemorizedMCP
cargo build --release

The binary will be at target/release/memory_mcp_server.exe.

---

🎯 Quick Start

1. Start the Server

MCP Mode (STDIO):

memory_mcp_server

HTTP Mode:

memory_mcp_server --bind 127.0.0.1:8080

2. Configure Cursor/MCP Client

Add to your MCP config (~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "memorized": {
      "command": "C:/path/to/memory_mcp_server.exe",
      "args": [],
      "env": {
        "DATA_DIR": "./data",
        "HTTP_BIND": "127.0.0.1:8080"
      }
    }
  }
}

3. Verify Health

# Via MCP tool
system.status

# Or via HTTP
curl http://127.0.0.1:8080/status

4. Ingest Your First Document

// Tool: document.store
{
  "mime": "md",
  "content": "# My Project\nThis is a Rust-based memory system."
}

5. Add a Memory

// Tool: memory.add
{
  "content": "MemorizedMCP uses hybrid search for fast retrieval",
  "layer_hint": "LTM",
  "references": [{ "docId": "<doc_id_from_step_4>" }]
}

6. Search Your Knowledge

// Tool: memory.search
{
  "q": "hybrid search",
  "limit": 10
}

---

💡 Usage Examples

Knowledge Graph Operations

Create an Entity:

// Tool: kg.create_entity
{ "entity": "Rust" }

Tag an Entity:

// Tool: kg.tag_entity
{
  "entity": "Rust",
  "tags": ["programming-language", "systems"]
}

Create a Relation:

// Tool: kg.create_relation
{
  "src": "Entity::Rust",
  "dst": "Entity::WebAssembly",
  "relation": "COMPILES_TO"
}

Search Entities by Tag:

// Tool: kg.get_tags
{ "tag": "programming-language" }

Memory Management

Add Memory with Episode Context:

// Tool: memory.add
{
  "content": "User prefers dark mode for code editor",
  "layer_hint": "STM",
  "session_id": "session_123",
  "episode_id": "setup_preferences"
}

Search with Temporal Filters:

// Tool: memory.search
{
  "q": "dark mode",
  "from": 1704067200000,
  "to": 1735689600000,
  "layer": "STM"
}

Consolidate STM → LTM:

// Tool: advanced.consolidate
{
  "dryRun": false,
  "limit": 50
}

---

📖 API Documentation

MCP Tools Reference

• MCP_Tools.md - Complete tool catalog with request/response schemas
• User-Guide.md - End-user guide for MCP clients
• Cursor Rules - AI agent integration patterns

Architecture Docs

• Architecture.md - System design and components
• Storage.md - Storage tiers and indexing strategies
• Memory-Layers.md - STM/LTM behavior and consolidation

Operations

• Operations.md - Deployment and monitoring
• Runbook.md - Incident response procedures
• Troubleshooting.md - Common issues and fixes

---

⚙️ Configuration

Environment Variables

Variable	Default	Description
HTTP_BIND	127.0.0.1:8080	HTTP server address (set empty to disable)
DATA_DIR	./data	Root directory for storage tiers
STM_CLEAN_INTERVAL_MS	60000	STM eviction check interval
LTM_DECAY_PER_CLEAN	0.99	LTM importance decay multiplier
FUSION_CACHE_TTL_MS	3000	Query cache time-to-live
MAX_CONCURRENT_INGEST	4	Document ingestion concurrency limit
STATUS_P95_MS_THRESHOLD	250	P95 latency threshold for health degradation

CLI Arguments

memory_mcp_server [OPTIONS]

Options:
  --bind <ADDR>      HTTP bind address (overrides HTTP_BIND)
  --data-dir <PATH>  Data directory root (overrides DATA_DIR)
  -h, --help         Print help
  -V, --version      Print version

---

🛠️ Development

Running Tests

cargo test

Benchmarks

cargo bench

Linting

cargo clippy -- -D warnings
cargo fmt --check

Building Documentation

cargo doc --open

Project Structure

MemorizedMCP/
├── server/
│   ├── src/
│   │   ├── main.rs         # HTTP/MCP server
│   │   ├── kg.rs           # Knowledge graph ops
│   │   ├── embeddings.rs   # Vector index
│   │   ├── vector_index.rs # HNSW ANN
│   │   └── config.rs       # Configuration
│   └── benches/            # Performance benchmarks
├── docs/                   # Documentation
├── scripts/                # Utility scripts
└── data/                   # Runtime data (gitignored)

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Code style and conventions
• Pull request process
• Issue reporting guidelines
• Development workflow

Areas for Contribution

• 🧪 Testing: Expand test coverage for edge cases
• 📊 Benchmarks: Add more realistic workload simulations
• 📚 Docs: Improve examples and tutorials
• 🔧 Features: See Roadmap.md for planned features
• 🐛 Bugs: Check Issues

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• MCP Protocol by Anthropic
• Tantivy for full-text search
• Sled for embedded KV storage
• Axum for HTTP serving

---

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ in Rust

⭐ Star this repo if you find it useful!

Report Bug · Request Feature · Documentation

Use these minimal tool calls from Cursor (or any other IDE that supports MCP servers) to interact with MemorizedMCP.

Installation

git clone the repo on your computer. then add :

"memorized-mcp": {
      "command": "your\\path\\to\\the\\git\\repo\\cloned\\target\\debug\\memory_mcp_server.exe",
      "args": [],
      "cwd": "your\\path\\to\\the\\git\\repo\\cloned\\MemorizedMCP",
      "env": {
        "DATA_DIR": "${workspaceFolder}\\.cursor\\memory",
        "RUST_LOG": "off"
      }
    }

NOTE: You can use ${workspaceFolder} or direct path to your project for the DATA_DIR.

Status

• Tool: system.status
• Arguments: {}
• Returns: JSON with uptime_ms, indices, storage, metrics, memory, health

Store a Document

• Tool: document.store
• Arguments:

{"mime":"md","content":"# Title\nHello"}

• Returns: { "id", "hash", "chunks" }

Retrieve a Document

• Tool: document.retrieve
• Arguments (one of):

{"id":"<DOC_ID>"}
{"path":"./README.md"}

Analyze a Document

• Tool: document.analyze
• Arguments:

{"id":"<DOC_ID>","includeEntities":true,"includeSummary":true}

Add a Memory

• Tool: memory.add
• Arguments:

{"content":"Project kickoff notes"}

Search Memories

• Tool: memory.search
• Arguments:

{"query":"kickoff","limit":5}

Update a Memory

• Tool: memory.update
• Arguments:

{"id":"<MEM_ID>","content":"updated"}

Delete a Memory

• Tool: memory.delete
• Arguments:

{"id":"<MEM_ID>","backup":true}

Hybrid Search (Fusion)

• Tool: memory.search (use query) or hit HTTP /search/fusion
• Tip: use time window filters: { "from": 0, "to": 9999999999999 }

Maintenance & Ops

• advanced.reindex → { "vector":true, "text":true, "graph":true }
• system.cleanup → { "compact":true }
• system.backup → { "destination":"./backups", "includeIndices":true }
• system.restore → { "source":"./backups/<snapshot>", "includeIndices":true }

References

• document.refs_for_memory → { "id":"<MEM_ID>" }
• document.refs_for_document → { "id":"<DOC_ID>" }
• document.validate_refs → { "fix": true }

Advanced Analytics

• advanced.analyze_patterns → { "window":{ "from":0, "to": 4102444800000 }, "minSupport": 2 }
• advanced.trends → { "from": 0, "to": 4102444800000, "buckets": 10 }
• advanced.clusters → {}
• advanced.relationships → {}
• advanced.effectiveness → {}