<p align="center">

</p>

<h1 align="center">Smriti MCP</h1>

<p align="center">
<a href="https://go.dev/"></a>
<a href="https://opensource.org/licenses/MPL-2.0"></a>
<a href="https://modelcontextprotocol.io/"></a>
<a href="https://hub.docker.com/r/tejzpr/smriti-mcp"></a>
<a href="https://github.com/tejzpr/smriti-mcp/actions"></a>
</p>

<p align="center"><strong>Graph-Based AI Memory System with EcphoryRAG Retrieval and Leiden Clustering</strong></p>

Smriti is a Model Context Protocol (MCP) server that provides persistent, graph-based memory for LLM applications. Built on LadybugDB (embedded property graph database), it uses EcphoryRAG-inspired multi-stage retrieval — combining cue extraction, graph traversal, vector similarity, and multi-hop association — to deliver human-like memory recall. Smriti uses the Leiden algorithm for automatic community detection, enabling cluster-aware retrieval that scales beyond thousands of memories.

Features

- Graph-Based Memory — Engrams (memories) linked via Cues and Associations in a property graph
- EcphoryRAG Retrieval — Multi-hop associative recall with cue extraction, vector similarity, and composite scoring
- Leiden Community Detection — Automatic clustering of related memories using the Leiden algorithm with smart-cached resolution tuning, enabling cluster-aware scoring for efficient retrieval at scale
- Multi-User Support — Separate LadybugDB per user, scales to thousands of isolated memory stores
- Automatic Consolidation — Exponential decay, pruning of weak memories, strengthening of frequently accessed ones, and periodic Leiden re-clustering
- Flexible Backup — GitHub (system git) or S3 (AWS SDK) sync, plus noop for local-only
- Lazy HNSW Indexing — Vector and FTS indexes created on-demand when dataset exceeds threshold
- OpenAI-Compatible APIs — Works with any OpenAI-compatible LLM and embedding provider
- 3 MCP Tools — smriti_store, smriti_recall, smriti_manage

Architecture

graph TD
    Client["MCP Client<br/>(Cursor / Claude / Windsurf / etc.)"]
    Client -->|stdio| Server
subgraph Server["Smriti MCP Server"]

        direction TB
subgraph Tools["MCP Tools"]

            Store["smriti_store"]

            Recall["smriti_recall"]

            Manage["smriti_manage"]

        end
subgraph Engine["Memory Engine"]

            Encoding["Encoding<br/>LLM + Embed + Link"]

            Retrieval["Retrieval<br/>Cue Match + Vector + Multi-hop<br/>+ Cluster-Aware Scoring"]

            Consolidation["Consolidation<br/>Decay + Prune + Leiden Clustering"]

        end
subgraph DB["LadybugDB (Property Graph)"]

            Graph["(Engram)──[:EncodedBy]──▶(Cue)<br/>(Engram)──[:AssociatedWith]──▶(Engram)<br/>(Cue)──[:CoOccurs]──▶(Cue)"]

        end
subgraph Backup["Backup Provider (optional)"]

            Git["GitHub (git)"]

            S3["S3 (AWS SDK)"]

            Noop["Noop"]

        end
Store & Recall & Manage --> Engine

        Encoding & Retrieval & Consolidation --> DB

        DB --> Backup

    end
LLM["LLM / Embedding API<br/>(OpenAI-compatible)"]

    Engine --> LLM

Recall Pipeline

The default recall mode performs multi-stage retrieval:

1. Cue Extraction — LLM extracts entities and keywords from the query
2. Cue-Based Graph Traversal — Follows EncodedBy edges to find engrams linked to matching cues
3. Vector Similarity Search — Cosine similarity against all engram embeddings (HNSW index when available, fallback to brute-force)
4. Multi-Hop Expansion — Follows AssociatedWith edges to discover related memories
5. Cluster-Aware Composite Scoring — Blends vector similarity (40%), recency (20%), importance (20%), and decay (20%), with hop-depth penalty and soft-bounded cross-cluster penalty (0.5x for hop results outside the seed cluster)
6. Access Strengthening — Recalled engrams get their access count and decay factor bumped (reinforcement)

Leiden Clustering

Smriti uses the Leiden algorithm — an improvement over Louvain that guarantees well-connected communities — to automatically detect clusters of related memories in the graph.

How it works:
- Runs automatically during each consolidation cycle
- Builds a weighted undirected graph from AssociatedWith edges between engrams
- Auto-tunes the resolution parameter using community profiling on the first run
- Uses a smart cache: the tuned resolution is reused across runs and only re-tuned when the graph grows by more than 10%
- Assigns a cluster_id to each engram, stored persistently in the database
- New engrams inherit the cluster_id of their strongest neighbor at encode time

How it improves retrieval:
- The recall pipeline determines a seed cluster (most common cluster among direct-match results)
- Multi-hop results that cross into a different cluster receive a 0.5x score penalty (soft-bounded: they are penalized, not dropped)
- This keeps retrieval focused within the most relevant topic cluster while still allowing cross-topic discovery

Performance characteristics:
- Gracefully skips on small graphs (< 3 nodes or 0 edges)
- Clustering 60 nodes: ~40ms (first run with auto-tune), ~14ms (cached resolution)
- Per-user: each Engine instance maintains its own independent cache

Consolidation Pipeline

Consolidation runs periodically (default: every 3600 seconds) and performs:

1. Exponential Decay — Reduces decay_factor based on time since last access
2. Weak Memory Pruning — Removes engrams below minimum decay threshold
3. Frequency Strengthening — Boosts decay factor for frequently accessed memories
4. Orphaned Cue Cleanup — Removes cues no longer linked to any engram
5. Leiden Clustering — Re-clusters the memory graph (smart-cached, skips if graph hasn't changed significantly)
6. Index Management — Creates HNSW vector and FTS indexes when engram count exceeds threshold (50)

Requirements

- Go 1.25+ — For building from source
- Git 2.x+ — Required for GitHub backup provider (must be in PATH)
- GCC/Build Tools — Required for CGO (LadybugDB)
- macOS: xcode-select --install
- Linux: sudo apt install build-essential
- Windows: Use Docker (recommended) or MinGW
- liblbug (LadybugDB shared library) — Runtime dependency, downloaded automatically by go-ladybug during build. If building manually, grab the latest release from LadybugDB/ladybug:

| Platform | Asset | Library |
|----------|-------|---------|
| macOS | liblbug-osx-universal.tar.gz | liblbug.dylib |
| Linux | liblbug-linux-{arch}.tar.gz | liblbug.so |
| Windows | liblbug-windows-x86_64.zip | liblbug.dll |

The shared library must be on the system library path at runtime (e.g., DYLD_LIBRARY_PATH on macOS, LD_LIBRARY_PATH on Linux, or alongside the binary on Windows). Docker and release binaries bundle this automatically.

Quick Start

1. Build

# Build
CGO_ENABLED=1 go build -o smriti-mcp .
Run (minimal config)
export LLM_API_KEY=your-api-key
export ACCESSING_USER=alice
./smriti-mcp

2. MCP Client Integration

Option 1: Native Binary

…