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.

Rust MCP License

---

✨ 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

---

======= # MCP Quickstart

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 → {}