Reverie — graph memory that dreams

Reverie is KnowAll AI's Neo4j knowledge-graph memory for AI agents, served over MCP. Until @knowall-ai/reverie is published to npm, install the legacy package @knowall-ai/mcp-neo4j-agent-memory (0.2.x). 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 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 @knowall-ai/mcp-neo4j-agent-memory   # becomes `npx @knowall-ai/reverie` once 0.4.0 is published

Or add it to your Claude Desktop configuration:

{
  "mcpServers": {
    "neo4j-memory": {
      "command": "npx",
      "args": ["@knowall-ai/mcp-neo4j-agent-memory"],
      "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 Behavior

search_memories is hybrid: keyword hits (any word of the query as a substring of any searchable content property) rank first, then semantic matches above a similarity threshold. 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 now supports three modes:

• hybrid (default): keyword hits score 1, then semantic matches add close variants such as Benjamin Weeks for Ben Weeks
• keyword: any word of the query as a substring of any searchable content property (timestamps, status and embedding fields are never matched)
• semantic: uses embeddings only when available, with graceful fallback to keyword behavior if embeddings are unavailable
• 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. Results include _score and _match on each returned memory object so callers can explain why a memory was returned.

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 and semantic search; Ben Weeks can also find Benjamin Weeks
  • Choose search_mode = hybrid, keyword, or semantic
  • Tune semantic strictness with similarity_threshold (default 0.4)
  • Returned memories include _score and _match metadata
  • 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

2. Node.js (v18 or higher)

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

3. Claude Desktop (for MCP integration)

   • Download from claude.ai/download

Installation

MCP Registry