Cozo Memory

CozoDB Memory MCP Server

Why Cozo Memory?

LLMs have short-term memory limits. Standard RAG retrieves documents but can't connect facts across time. Cozo Memory gives your AI agent persistent, structured memory – it remembers past conversations, infers relationships, detects contradictions, and explores its knowledge graph – fully on your machine, with optional local LLM integration via Ollama for intelligent actions (cleanup, reflection, summarization, agentic routing).

Most memory stacks combine separate databases: SQLite for facts, Chroma for vector search, NetworkX for graphs. CozoDB replaces all of that with one embedded engine: relational, graph, vector, and full-text search in a single query language, one file, zero sync lag.

Local-first memory for Claude & AI agents with hybrid search, Graph-RAG, and time-travel – runs entirely on your machine. Optional [Ollama](https://ollama.ai) integration enables LLM-powered actions (cleanup, reflect, summarize, agentic retrieval).

Table of Contents

• Quick Start
• Key Features
• Positioning & Comparison
• Installation
• Integration
• Documentation
• Troubleshooting

Quick Start

Option 1: Install via npm (Recommended)

# Install globally

npm install -g cozo-memory

Or run directly with npx (no installation needed)

npx cozo-memory

Option 2: Build from Source

git clone https://github.com/tobs-code/cozo-memory

cd cozo-memory npm install && npm run build npm run start

Now add the server to your MCP client (e.g. Claude Desktop) – see Integration below.

Key Features

🔍 Hybrid Search - Combines semantic (HNSW), full-text (FTS), and graph signals via Reciprocal Rank Fusion for intelligent retrieval

🧠 Agentic Retrieval - Auto-routing engine analyzes query intent via local LLM to select optimal search strategy (Vector, Graph, or Community)

⏱️ Time-Travel Queries - Version all changes via CozoDB Validity; query any point in history with full audit trails

🎯 GraphRAG-R1-Inspired Adaptive Retrieval - Intelligent system with Progressive Retrieval Attenuation (PRA) and Cost-Aware F1 (CAF) scoring, conceptually inspired by GraphRAG-R1 (Yu et al., WWW 2026) and adapted for CozoDB, that learns from usage

⏳ Temporal Conflict Resolution - Automatic detection and resolution of contradictory observations with semantic analysis and audit preservation

🏠 100% Local - Embeddings via ONNX/Transformers; data stays on your machine. Some advanced features (cleanup, reflect, summarize, agentic search) require an optional Ollama service for local LLM inference — but the core search, CRUD, and graph operations work without any LLM.

🧠 Multi-Hop Reasoning - Logic-aware graph traversal with vector pivots for deep relational reasoning

🗂️ Hierarchical Memory - Multi-level architecture (L0-L3) with intelligent compression and LLM-backed summarization

[→ See all features](docs/FEATURES.md) | [Version History](CHANGELOG.md)

Positioning & Comparison

Why CozoDB instead of SQLite + Chroma + NetworkX?

A common first question is: *"Why not just combine existing tools?"*

The core insight: Most memory stacks bolt vector search onto a graph DB, or graph search onto a vector DB. CozoDB is different: it is a single engine that natively combines relational, graph, vector, and full-text search. That means:

• One query language (Datalog) reaches every dimension.
• No sync lag between separate indexes.
• No ETL bridge between "vector results" and "graph expansion."
• Smaller operational surface: one database file, one process, one dependency chain.

Comparison with other memory solutions

Most "Memory" MCP servers fall into two categories:

1. Simple Knowledge Graphs: CRUD operations on triples, often only text search
2. Pure Vector Stores: Semantic search (RAG), but little understanding of complex relationships

This server fills the gap in between ("Sweet Spot"): A local, database-backed memory engine combining vector, graph, and keyword signals — powered by CozoDB's unified engine rather than a patchwork of separate databases.

The core advantage is Intelligence and Traceability: By combining an Agentic Retrieval Layer with Hierarchical GraphRAG, the system can answer both specific factual questions and broad thematic queries with much higher accuracy than pure vector stores.

Installation

Prerequisites

• Node.js 20+ (recommended)
• RAM: 1.7 GB minimum (for default bge-m3 model)
• Model download: ~600 MB
• Runtime memory: ~1.1 GB
• ⚡ Too heavy? Use EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 – only ~400 MB RAM needed (see Embedding Model Options)
• CozoDB native dependency is installed via cozo-node

Optional: Ollama for LLM-powered actions

Some advanced actions use a local LLM via Ollama for intelligent processing. The core server works without Ollama (CRUD, search, graph operations), but the following actions require it:

Setup (if you need these features):

# 1. Install Ollama from https://ollama.ai

2. Pull a model (e.g. small + fast for dev):

ollama pull demyagent-4b-i1:Q6_K

3. Ollama runs automatically on http://localhost:11434

If Ollama is not running, the affected actions gracefully fall back to non-LLM behavior (where possible) or return a clear error message.

Via npm (Easiest)

# Install globally

npm install -g cozo-memory

Or use npx without installation

npx cozo-memory

From Source

git clone https://github.com/tobs-code/cozo-memory

cd cozo-memory npm install npm run build

Windows Quickstart

npm install

npm run build npm run start

Notes:

• On first start, @xenova/transformers downloads the embedding model (may take time)
• Embeddings are processed on the CPU

Embedding Model Options

CozoDB Memory supports multiple embedding models via the EMBEDDING_MODEL environment variable:

Configuration Options:

Option 1: Using `.env` file (Easiest for beginners)

# Copy the example file

cp .env.example .env

Edit .env and set your preferred model

EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

Option 2: MCP Server Config (For Claude Desktop / Kiro)

{

"mcpServers": { "cozo-memory": { "command": "npx", "args": ["cozo-memory"], "env": { "EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2" } } } }

Option 3: Command Line

# Use lightweight model for development

EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run start

Download Model First (Recommended):

# Set model in .env or via command line, then:

EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run download-model

Note: Changing models requires re-embedding existing data. The model is downloaded once on first use.

Integration

Claude Desktop

Using npx (Recommended)

{

"mcpServers": { "cozo-memory": { "command": "npx", "args": ["cozo-memory"] } } }

Using global installation

{

"mcpServers": { "cozo-memory": { "command": "cozo-memory" } } }

Using local build

{

"mcpServers": { "cozo-memory": { "command": "node", "args": ["C:/Path/to/cozo-memory/dist/index.js"] } } }

Framework Adapters

Official adapters for seamless integration with popular AI frameworks:

🦜 LangChain Adapter

npm install @cozo-memory/langchain @cozo-memory/adapters-core

import { CozoMemoryChatHistory, CozoMemoryRetriever } from '@cozo-memory/langchain';

const chatHistory = new CozoMemoryChatHistory({ sessionName: 'user-123' }); const retriever = new CozoMemoryRetriever({ useGraphRAG: true, graphRAGDepth: 2 });

🦙 LlamaIndex Adapter

npm install @cozo-memory/llamaindex @cozo-memory/adapters-core

import { CozoVectorStore } from '@cozo-memory/llamaindex';

const vectorStore = new CozoVectorStore({ useGraphRAG: true });

Documentation: See adapters/README.md for complete examples and API reference.

CLI & TUI

CLI Tool

Full-featured CLI for all operations:

# System operations

cozo-memory system health cozo-memory system metrics

Entity operations

cozo-memory entity create -n "MyEntity" -t "person" cozo-memory entity get -i

Search

cozo-memory search query -q "search term" -l 10 cozo-memory search agentic -q "agentic query"

Graph operations

cozo-memory graph pagerank cozo-memory graph communities

Export/Import

cozo-memory export json -o backup.json cozo-memory import file -i data.json -f cozo

All commands support -f json or -f pretty for output formatting

See CLI help for complete command reference: `cozo-memory --help`

TUI (Terminal User Interface)

Interactive TUI with mouse support powered by Python Textual:

#