Memnest Memory MCP Server

Persistent graph memory for AI agents using LadybugDB — an embedded graph database with native vector search and full-text search.

Give your AI agent memory that persists across sessions, deduplicates automatically, and models knowledge as a graph with typed relationships.

Why Memnest?

• Graph memory — memories linked via Topic nodes and relationships (RELATED_TO, SUPERSEDES, EXPLAINS) with Cypher queries
• Three-layer auto-dedup — exact hash + semantic similarity + LLM-driven consolidation
• Workspace namespacing — memories scoped per project; global_search opt-out
• HNSW vector search — fast cosine similarity over FastEmbed embeddings
• Topic auto-linking — tags become graph nodes, enabling traversal queries
• Embedded — no Docker, no server process, single database directory
• Zero config — sensible defaults, just install and run
• Importance & access tracking — memories ranked by relevance and usage

Benchmarks

Memnest scores 82.9% on the LOCOMO benchmark — the standard evaluation for long-term conversational memory (ACL 2024).

Evaluated with Claude Sonnet 4.5 as the answer agent and Haiku 4.5 as the judge, using the industry-standard LLM-as-a-Judge methodology. All 5 LOCOMO categories included.

Architecture advantages

• Zero LLM calls in the server — intelligence lives in the agent, not the memory layer
• Local embeddings — no API key needed (bge-small-en-v1.5, 384-dim)
• Single embedded database — no Docker, no PostgreSQL, no separate vector DB
• Hybrid search — Vector (HNSW) + Full-text (BM25) + Graph (PageRank + Louvain communities)
• 3 agent tools — memory_search, memory_get, calculator. Simple interface, powerful retrieval.

Quick Start

# Run directly with uvx (no install needed)
uvx memnest-mcp

Or install and run:

pip install memnest-mcp
memnest-mcp

MCP Configuration

Add to your MCP client config (Kiro, Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "memnest": {
      "command": "uvx",
      "args": ["memnest-mcp@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

That's it — zero config required. All settings have sensible defaults.

Tools

Graph Data Model

(:Memory)  — content, embedding, category, tags, importance, access_count, timestamps
(:Topic)   — auto-created from tags

(:Memory)-[:ABOUT]->(:Topic)          # memory is about a topic
(:Memory)-[:RELATED_TO]->(:Memory)    # memories are related
(:Memory)-[:SUPERSEDES]->(:Memory)    # newer memory replaces older

Example: Store and Search

# Store a memory (via MCP tool call)
memory_store(
    content="User prefers Python over Node.js for backend tools",
    category="preference",
    tags=["python", "nodejs", "backend"],
    importance=4
)

# Search memories
memory_search(query="what language does the user prefer")

# Traverse the graph
memory_query(
    cypher_query="MATCH (m:Memory)-[:ABOUT]->(t:Topic {name: 'python'}) RETURN m.content"
)

Example: Graph Relationships

# Link related memories
memory_relate(from_id=5, to_id=3, relationship="RELATED_TO")

# Mark a decision as superseded
memory_relate(from_id=8, to_id=2, relationship="SUPERSEDES")

# Find all memories about a topic
memory_query(
    cypher_query="MATCH (m:Memory)-[:ABOUT]->(t:Topic) RETURN t.name, COUNT(m) ORDER BY COUNT(m) DESC"
)

Three-Layer Deduplication

Every memory_store call runs through three dedup layers:

1. Exact hash — SHA256 of normalized content. Identical content is rejected, importance bumped.
2. Semantic similarity — If cosine similarity > 0.92 with an existing memory, merges into it (keeps longer content, merges tags, bumps importance).
3. Consolidation — Periodic via memory_dream. Auto-prunes stale low-importance memories, auto-merges trivial duplicates (similarity ≥ 0.95), surfaces clusters for LLM-driven review.

Categories

Configuration

All settings are optional — defaults work out of the box.

In-Memory Mode (Testing)

"env": { "MEMORY_DB_PATH": ":memory:" }

All data is ephemeral — lost on restart. Useful for testing.

Kiro Power

This repo includes a ready-to-use Kiro Power in the power/memnest/ directory with:

• Pre-configured MCP server (power/memnest/mcp.json)
• Three hooks for automatic memory persistence and recall (power/memnest/hooks/)
• persist-memory — stores important info when the agent stops
• recall-memory — searches memory before responding to each prompt
• auto-dream — manually trigger consolidation (prune + merge + review)
• Steering files with setup guide and Cypher query examples (power/memnest/steering/)

Install in Kiro: Add Custom Power → https://github.com/arunkumars-mf/memnest-mcp/tree/main/power/memnest

Architecture

AI Agent (Kiro, Claude, etc.)
    │
    ├─ memory_store ──→ embed content → dedup check → insert node → link topics
    ├─ memory_search ─→ embed query → HNSW vector search → tag boost → rank
    ├─ memory_query ──→ execute Cypher → return graph results
    │
    └─ LadybugDB (embedded, single directory)
        ├─ Memory nodes (content + FLOAT[384] embeddings)
        ├─ Topic nodes (auto-linked from tags)
        ├─ HNSW vector index (cosine similarity)
        └─ Graph relationships (ABOUT, RELATED_TO, SUPERSEDES, EXPLAINS)

Requirements

• Python 3.10+
• Dependencies installed automatically: real-ladybug, fastembed, mcp
• ~130MB disk for the embedding model (downloaded on first run)

TOON Format (Optional)

Memnest supports TOON (Token-Oriented Object Notation) as a response format, reducing token usage by 30–60% compared to JSON. This is useful when memory results are fed back into LLM context.

TOON is optional — the server falls back to compact JSON automatically if the package isn't installed. To enable it:

pip install "memnest-mcp[toon]"

Or with uvx (requires the --prerelease=allow flag since toon-format is currently in beta):

uvx --prerelease=allow --with "toon-format==0.9.0b1" memnest-mcp@latest

To switch formats at runtime, set the environment variable:

MEMORY_RESPONSE_FORMAT=toon   # compact, token-efficient (default when installed)
MEMORY_RESPONSE_FORMAT=json   # standard JSON (default when toon is not installed)

The official Python implementation of TOON is toon-format/toon-python, currently at v0.9.0-beta.1. Once it reaches a stable 1.0 release, the --prerelease=allow flag will no longer be necessary.

Contributing

Issues and PRs welcome. See LICENSE for terms.

License

MIT

Changelog

0.3.0

• Default database is now per-workspace: .memnest/memory.lbug in the current directory. No more cross-workspace lock conflicts.
• Set MEMORY_DB_PATH to use a custom location (e.g. ~/.memnest/memory.lbug for global shared memory).
• Hybrid search: Vector (HNSW) + Full-text (BM25) + Graph scoring with PageRank, Louvain community detection, and K-Core decomposition.
• LOCOMO benchmark: 82.9% overall score.

0.2.0

Compatibility-preserving redesign with improved safety defaults.

• New tools: memory_query (general Cypher), memory_schema, memory_topics, memory_dream, memory_graph_html. Batch mode added to memory_store, memory_update, memory_relate, memory_delete.
• Breaking: MEMORY_ALLOW_DESTRUCTIVE now defaults to false. Set it to true if you previously relied on memory_query deleting nodes.
• Breaking: tag storage migrated from comma-joined strings to JSON arrays. Old rows are still readable; rewriting (e.g. via memory_update) upgrades them to JSON.
• memory_get, memory_list, memory_traverse from 0.1.x are retained as compatibility aliases. They will be removed in 0.3.0.
• TOON serialization is now the default response format when toon-format is installed; set MEMORY_RESPONSE_FORMAT=json to opt out.
• memory_relate validates that both endpoints exist before returning created (used to silently no-op on typo'd IDs).
• memory_graph_html is now XSS-safe (HTML-escaped tooltips, DOM textContent for the detail panel), refuses to render >MEMORY_GRAPH_MAX_NODES, and rotates snapshots.
• Workspace filter pushed inside the vector index WITH clause so search recall isn't starved across workspaces.
• Dream consolidation: dedupes parallel edges across merges, isolates clusters by workspace, persists state via atomic sidecar JSON.