better-memory

Better Memory MCP Server provides a persistent knowledge graph memory system designed to help Claude maintain and organize knowledge across conversations. It supports entities, relations, and rich observations with timestamps and confidence scores, plus advanced features such as semantic search via ModernColBERT, entity archiving, merging, and a recent changes view. The server exposes a suite of tools for manipulating the graph: create_entities and create_relations to build the graph, add_observations to enrich entities with time-stamped facts, and read_graph or open_nodes to inspect data. Semantic search lets you retrieve relevant entities by meaning rather than exact keyword matching, while backfilling ensures existing memories become indexable for faster semantic retrieval on first use. You can archive or unarchive entities to soft-delete and restore data without losing your history, and you can merge duplicate entities to consolidate observations and relations. For day-to-day usage, you’ll typically start the server locally, then issue API-like calls to perform creation, updates, and queries against the memory graph.

Prerequisites:

• Python 3.8 or newer
• Optional: Node.js for building/using accompanying front-end tooling
• Git

Quick setup (recommended):

1. Clone the repository and install dependencies: git clone https://github.com/sockeye44/better-memory-mcp cd better-memory-mcp ./setup.sh

   The setup script will:

   • Verify Python 3.8+ is installed
   • Create a Python virtual environment
   • Install Python dependencies (including PyTorch and ModernColBERT)
   • Pre-download neural models for semantic search
   • Install Node.js dependencies and build the TypeScript code

2. Run the server: python server.py

Manual setup (if the script fails):

1. Install Python dependencies: pip install -r requirements.txt

2. Install Node.js dependencies (optional for frontend/tools): npm install

3. Build TypeScript (optional for frontend/tools): npm run build

Note: Semantic search requires Python 3.8+ and PyTorch. If these are not available, the server will still function with keyword-based search only.

Tips and caveats:

• Semantic search relies on ModernColBERT embeddings; ensure the required models are downloaded and accessible at runtime. If the model isn’t available, the system will gracefully fall back to keyword search.
• Observations are atomic; store one fact per observation to simplify merging, archiving, and deletion operations.
• Use archive_entity and unarchive_entity to soft-delete or restore entities without losing historical data.
• When adding observations, you can assign per-observation confidence scores (0-1) to express certainty.
• The get_recent_changes tool lets you filter by a time window (hours) to monitor recent activity across entities, relations, and observations.
• If you modify underlying data structures, consider running read_graph with detailLevel set to full to verify consistency across entities and relations.
• Backfill: On first use, semantic indexing may backfill memories automatically; ensure the system has sufficient compute resources for indexing large memories.