Reverie

Reverie — graph memory that dreams

Reverie is KnowAll AI's Neo4j knowledge-graph memory for AI agents, served over MCP. It is published on npm as @knowall-ai/reverie (successor to the legacy package @knowall-ai/mcp-neo4j-agent-memory). The GitHub repository is now knowall-ai/mcp-reverie, and old URLs redirect.

Reverie turns an agent's memory from a pile of facts into a map of the entities in its world and how they relate, and keeps that map healthy. It is an MCP server, so any agent that speaks the Model Context Protocol (Claude Desktop, OpenClaw, Azure AI Foundry, Cursor…) gets the same graph; a Hermes Agent memory-provider flavour lives in hermes-reverie.

Why Reverie

• A typed entity graph, not a fact store. People, organisations, projects, places, concepts, meetings and decisions are nodes with typed relationships. "Who at the Irish FA have we talked to about Winnie?" is a graph walk, not a similarity search.
• Search that finds "Ben" when you say "Benjamin". Hybrid keyword + semantic + fuzzy name search, with local embeddings by default (no API key) and OpenAI, Azure OpenAI, Ollama or Voyage a config switch away.
• It dreams. A dream tool merges duplicates safely, canonicalises labels, re-embeds, counts orphans and flags nodes that have become property dumps, so a nightly job can keep the graph clean.
• One graph, any agent. KnowAll runs Sallie (OpenClaw) and Poppie (Hermes) against the same conventions; Reverie is how they share what they know.
• LLM-driven, transparent tools. Simple atomic operations; the model does the entity recognition and conflict resolution, and every action is explicit.
• Yours to run. Neo4j on your own machine or VM. Nothing leaves it unless you choose a remote embedding provider.

Quick Start 🚀

You can run this MCP server directly using npx:

npx -y @knowall-ai/reverie

Or add it to your Claude Desktop configuration:

{

"mcpServers": { "reverie": { "command": "npx", "args": ["-y", "@knowall-ai/reverie"], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USERNAME": "neo4j", "NEO4J_PASSWORD": "your-password", "NEO4J_DATABASE": "neo4j" } } } }

Features

• 🧠 Persistent Memory Storage - Store and retrieve memories across conversations
• 🔗 Semantic Relationships - Create meaningful connections between memories (KNOWS, WORKS_AT, CREATED, etc.)
• 🔍 Hybrid Search - Keyword plus semantic search across all memory properties, with local embeddings by default
• 🏷️ Flexible Labeling - Use any label for memories (person, place, project, idea, etc.)
• ⏰ Temporal Tracking - Automatic timestamps and date-based queries
• 🌐 Graph Exploration - Traverse relationships to discover connected information
• 🎯 Context-Aware - Search with depth to include related memories
• 🔧 LLM-Optimized - Simple tools that let the AI handle the complexity
• 🏢 Enterprise Ready - Supports multiple Neo4j databases
• 📚 Built-in Guidance - Get help on best practices and usage patterns

Philosophy: LLM-Driven Intelligence

Unlike traditional approaches that embed complex logic in tools, this server provides simple, atomic operations and lets the LLM handle all the intelligence:

• No hidden logic: Tools do exactly what they say - no auto-disambiguation or smart matching
• LLM decides everything: Entity recognition, relationship inference, and conflict resolution
• Transparent operations: Every action is explicit and predictable
• Maximum flexibility: The LLM can implement any strategy without tool limitations

Search Behaviour

search_memories is hybrid: each result ranks by its best keyword, semantic or fuzzy name signal. See Search below.

This approach makes the system more powerful and adaptable, as improvements in LLM capabilities directly translate to better memory management.

Search

search_memories supports four matching signals — keyword, semantic, fuzzy and exact — through these modes:

• hybrid (default): rank by the best signal — keyword share of query words, semantic cosine or fuzzy name similarity
• keyword: any word of the query as a substring of any searchable content property (timestamps, status and embedding fields are never matched)
• semantic: embeddings only; if embeddings are unavailable it falls back to keyword matching (and hybrid keeps its keyword and fuzzy signals)
• fuzzy: match misspelled or misheard names and aliases using spelling, prefixes and phonetics; "Ben Wicks" can find "Benjamin Weeks" without embeddings
• exact: case-insensitive equality on name, aliases or email; the precise lookup to run before creating a memory, so "ben weeks" finds exactly "Ben Weeks" and nothing else

Archived memories (status = 'archived') are left out of results and of list_memory_labels unless include_archived: true is passed. Returned relationships carry _start and _end node ids, so a connection's direction is always recoverable.

Use similarity_threshold (default 0.4; must be between 0 and 1, other values are rejected) to control how strict semantic matches are. Use fuzzy_threshold (default 0.85, range 0–1) for fuzzy strictness. Results include _score, _match and, for fuzzy hits, _matched (the stored name or alias). Confirm differing names with the user; nicknames such as Bill/William need aliases.

Neo4j Enterprise Support

This server now supports connecting to specific databases in Neo4j Enterprise Edition. By default, it connects to the "neo4j" database, but you can specify a different database using the NEO4J_DATABASE environment variable.

Memory Tools

• search_memories: Search and retrieve memories from the knowledge graph
• Hybrid search: Blend keyword, semantic and fuzzy name search; Ben Wicks can find Benjamin Weeks
• Choose search_mode = hybrid, keyword, semantic, fuzzy or exact
• Tune similarity_threshold (default 0.4) and fuzzy_threshold (default 0.85)
• Returned memories include _score, _match and _matched for fuzzy hits
• Filter by memory type (case-insensitive, so person and Person both work), date, depth, result limit, and sort order

• create_memory: Create a new memory in the knowledge graph
• Flexible type system - any label that is a plain identifier; Capitalised singular is canonical (Person, Place, Project, Skill…), and dream canonicalises lowercase labels
• Store any properties as key-value pairs
• Automatic timestamps for temporal tracking

• create_connection: Create relationships between memories
• Link memories using semantic relationship types (KNOWS, WORKS_AT, LIVES_IN, etc.)
• Add properties to relationships (since, role, status, etc.)
• Build complex knowledge networks

• update_memory: Update properties of existing memories
• Returns a _hint when the node exceeds the property limit: the graph is for entities and relationships, not a notebook
• Add or modify any property
• Set properties to null to remove them

• update_connection: Update relationship properties
• Modify relationship metadata
• Track changes over time

• delete_memory: Remove memories and all their connections
• Use with caution - permanent deletion
• Automatically removes all relationships

• delete_connection: Remove specific relationships
• Precise relationship removal
• Keeps the memories intact

• list_memory_labels: List all unique memory labels in use
• Shows all labels with counts
• Helps maintain consistency
• Prevents duplicate label variations

• query_memories: Run a read-only Cypher query
• Accepts a Cypher string plus optional params
• Runs in a Neo4j READ transaction (the server rejects writes), stops after 200 rows, and times out after 10 seconds
• Rejects write clauses, CALL subqueries, and any procedure outside a small read-only allow-list (db.labels, db.propertyKeys, db.index.*.query*, schema procedures). For belt and braces, run the server with a read-only Neo4j role where you can

• memory_stats: Summarize the current graph
• Returns node, relationship, label, relationship-type, embedding, and orphan counts

• dream: Deterministically clean up and consolidate the graph
• Relabels lowercase labels to their Capitalised form (person → Person), merges same-named nodes within a label when APOC is available, and refreshes embeddings
• Merging keeps the survivor's name, timestamps and vectors and combines every other property (conflicting values become lists, nothing is dropped) and skips pairs whose identity fields differ (email, phone, website, company, organisation, organization), so two different "John Smith"s stay separate. The report lists every group under duplicates with what was merged and what was skipped and why. Run with dry_run: true first to review
• Reports bloated nodes (more than REVERIE_MAX_PROPERTIES, default 30, real properties) with the keys that look like dated facts or prose, so a nightly sleep can fold them into attributes, relationships or notes
• Supports dry_run for a no-write report

• get_guidance: Get help on using the memory tools effectively
• Topics: labels, relationships, best-practices, examples
• Returns comprehensive guidance for LLMs
• Use when uncertain about label/relationship naming

Prerequisites

1. Neo4j Database 5.9 or newer (the dream tool uses COUNT {} and IS :: STRING); APOC for duplicate merging

• Install Neo4j Community or Enterprise Edition
• Download from neo4j.com/download
• Or use Docker: docker run -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j

1. Node.js (v18 or higher)

• Required to run the MCP server
• Download from nodejs.org

1. Claude Desktop (for MCP integration)

• Download from claude.ai/download

Installation

MCP Registry

Reverie is listed in the MCP Registry as ai.knowall/reverie (KnowAll's domain namespace, verified by a DNS TXT record on knowall.ai) (the successor of the "Neo4j Agent Memory" entry that used to sit in the modelcontextprotocol/servers README). server.json in this repository is the listing; the release workflow republishes it on every tag.

Installing via Smithery

To install Reverie for Claude Desktop automatically via Smithery (currently indexed under its legacy package name):

npx -y @smithery/cli install @knowall-ai/mcp-neo4j-agent-memory --client claude

For Development

1. Clone the repository:

git clone https://github.com/knowall-ai/mcp-reverie.git

cd mcp-reverie

1. Install dependencies:

npm install

1. Build the project:

npm run build

Configuration

Environment Variables

The server requires the following environment variables:

• NEO4J_URI: Neo4j database URI (required, e.g., bolt://localhost:7687)
• NEO4J_USERNAME: Neo4j username (required)
• NEO4J_PASSWORD: Neo4j password (required)
• NEO4J_DATABASE: Neo4j database name (optional) - For Neo4j Enterprise with multiple databases

Embeddings

Set REVERIE_EMBEDDINGS to choose the embedding provider used by hybrid and semantic search. Changing REVERIE_EMBEDDINGS or REVERIE_EMBEDDING_MODEL causes nodes to be re-embedded lazily on the nex