cozo-memory

CozoDB Memory MCP 服务

为什么选择 Cozo Memory？
大模型的短期记忆有限。标准 RAG 可以检索文档，却无法将不同时期的事实联系起来。Cozo Memory 为你的 AI Agent 提供持久化的结构化记忆——它能记住过去的对话、推断关系、检测矛盾，并探索其知识图谱——所有操作都在你的设备上完成；还可选择通过 Ollama 集成本地大模型，以执行智能操作（清理、反思、摘要、Agent 路由）。

大多数记忆技术栈都组合使用独立的数据库：用 SQLite 存储事实，用 Chroma 进行向量搜索，用 NetworkX 构建图。CozoDB 用一个嵌入式引擎取代所有这些工具：在一种查询语言、一个文件中实现关系、图、向量和全文搜索，无同步延迟。

为 Claude 和 AI Agent 打造的本地优先记忆，支持混合搜索、Graph-RAG 和时间回溯——完全在你的设备上运行。可选的 Ollama 集成可启用大模型驱动的操作（清理、反思、摘要、Agent 检索）。

目录

• 快速入门
• 主要功能
• 定位与比较
• 安装
• 集成
• 文档
• 故障排除

快速入门

选项 1：通过 npm 安装（推荐）

# Install globally
npm install -g cozo-memory

# Or run directly with npx (no installation needed)
npx cozo-memory

选项 2：从源代码构建

git clone https://github.com/tobs-code/cozo-memory
cd cozo-memory
npm install && npm run build
npm run start

现在将该服务添加到你的 MCP 客户端（例如 Claude Desktop）——请参阅下方的集成。

主要功能

🔍 混合搜索 - 通过 Reciprocal Rank Fusion 融合语义搜索（HNSW）、全文搜索（FTS）和图信号，实现智能检索

🧠 Agent 检索 - 自动路由引擎通过本地大模型分析查询意图，选择最佳搜索策略（Vector、Graph 或 Community）

⏱️ 时间回溯查询 - 通过 CozoDB Validity 为所有更改创建版本；查询历史中的任意时间点，并保留完整审计记录

🎯 受 GraphRAG-R1 启发的自适应检索 - 智能系统采用渐进式检索衰减（PRA）和成本感知 F1（CAF）评分，从概念上借鉴 GraphRAG-R1（Yu 等人，WWW 2026），并针对 CozoDB 进行了调整，可从使用情况中学习

⏳ 时序冲突解决 - 自动检测并解决相互矛盾的观察结果，同时进行语义分析并保留审计记录

🏠 100% 本地运行 - 通过 ONNX/Transformers 生成嵌入；数据留在你的设备上。部分高级功能（清理、反思、摘要、Agent 搜索）需要可选的 Ollama 服务来进行本地大模型推理——但核心搜索、CRUD 和图操作无需任何大模型即可运行。

🧠 多跳推理 - 具备逻辑感知能力的图遍历，结合向量枢纽，支持深度关系推理

🗂️ 分层记忆 - 多级架构（L0-L3），支持智能压缩和大模型驱动的摘要

→ 查看所有功能 | 版本历史

定位与比较

为什么选择 CozoDB，而不是 SQLite + Chroma + NetworkX？

一个常见的初步疑问是：“为什么不直接组合现有工具？”

如果你需要……	典型的独立技术栈	CozoDB Memory
结构化数据和关系	SQLite / PostgreSQL	✅ 内置关系引擎
语义 / 向量搜索	Chroma / Qdrant / Pinecone	✅ 在一个引擎中提供 HNSW + FTS + RRF
图遍历和推理	NetworkX / Neo4j	✅ 原生图查询 + PageRank
时间回溯 / 版本控制	自定义审计表	✅ 内置 Validity 时间回溯
统一查询语言	多个 API + 胶水代码	✅ 使用单一 Datalog 查询覆盖所有维度

核心洞见： 大多数记忆技术栈会在图数据库上添加向量搜索，或在向量数据库上添加图搜索。CozoDB 则与众不同：它是一个单一引擎，可原生结合关系、图、向量和全文搜索。这意味着：

• 一种查询语言（Datalog）即可访问所有维度。
• 独立索引之间没有同步延迟。
• “向量结果”和“图扩展”之间无需 ETL 桥接。
• 更小的运维范围：一个数据库文件、一个进程、一条依赖链。

与其他记忆解决方案的比较

大多数“记忆” MCP 服务分为两类：

1. 简单知识图谱：对三元组执行 CRUD 操作，通常只有文本搜索
2. 纯向量存储：语义搜索（RAG），但对复杂关系的理解能力有限

此服务填补了两者之间的空白（“最佳平衡点”）：一个由数据库支持的本地记忆引擎，结合向量、图和关键词信号——由 CozoDB 统一引擎驱动，而非由多个独立数据库拼凑而成。

特性	CozoDB Memory（本项目）	官方参考实现（@modelcontextprotocol/server-memory）	mcp-memory-service（社区版）	数据库适配器（Qdrant/Neo4j）
后端	CozoDB（在一个引擎中提供图 + 向量 + 关系 + FTS）	JSON 文件（memory.jsonl）	SQLite / Cloudflare	专用数据库（仅向量或图）
搜索逻辑	Agentic（自动路由）：混合 + 图 + 摘要	仅关键词 / 精确图匹配	向量 + 关键词	大多仅支持一个维度
推理	支持：内置引擎，可推断隐式知识	不支持	不支持（“Dreaming”指的是整合）	不支持（仅检索）
社区	支持：分层社区摘要	不支持	不支持	仅聚类（无摘要）
时间回溯	支持：查询任意时间点的数据（Validity）	不支持（仅当前状态）	可查看历史记录，但数据库原生不支持	不支持
维护	清理器：基于大模型的清理	手动	自动整合	大多需要手动操作
部署	本地（Node.js + 嵌入式数据库）	本地（Docker/NPX）	本地或云端	通常需要外部数据库服务

核心优势在于智能性和可追溯性：通过结合Agentic 检索层和分层 GraphRAG，系统能够以远高于纯向量存储的准确度回答具体事实问题和宽泛的主题类查询。

安装

前置条件

• Node.js 20+（推荐）
• RAM：至少 1.7 GB（适用于默认的 bge-m3 模型）
  • 模型下载：约 600 MB
  • 运行时内存：约 1.1 GB
  • ⚡ 资源占用太高？ 使用 EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2——仅需 约 400 MB RAM（参见嵌入模型选项）
• CozoDB 原生依赖通过 cozo-node 安装

可选：使用 Ollama 执行由大模型驱动的操作

某些高级操作会通过 Ollama 使用本地大模型进行智能处理。核心服务无需 Ollama 即可运行（CRUD、搜索、图操作），但以下操作需要 Ollama：

操作	用途
cleanup	使用大模型整合观察记录
reflect	生成洞见、检测矛盾
summarize_communities	使用大模型生成社区摘要
compact	使用大模型摘要压缩会话 / 实体
agentic_search	对查询意图进行分类，以便自动路由

设置（如需使用这些功能）：

# 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

如果 Ollama 未运行，受影响的操作会在可能的情况下退回到非大模型处理方式，或返回明确的错误消息。

通过 npm 安装（最简单）

# Install globally
npm install -g cozo-memory

# Or use npx without installation
npx cozo-memory

从源代码安装

git clone https://github.com/tobs-code/cozo-memory
cd cozo-memory
npm install
npm run build

Windows 快速入门

npm install
npm run build
npm run start

说明：

• 首次启动时，@xenova/transformers 会下载嵌入模型（可能需要一些时间）
• 嵌入处理由 CPU 执行

嵌入模型选项

CozoDB Memory 支持通过 EMBEDDING_MODEL 环境变量配置多个嵌入模型：

模型	大小	RAM	维度	适用场景
Xenova/bge-m3（默认）	~600 MB	~1.7 GB	1024	高准确度、生产环境
Xenova/all-MiniLM-L6-v2	~80 MB	~400 MB	384	低配设备、开发环境
Xenova/bge-small-en-v1.5	~130 MB	~600 MB	384	性能均衡

配置选项：

选项 1：使用 .env 文件（最适合初学者）

# Copy the example file
cp .env.example .env

# Edit .env and set your preferred model
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

选项 2：MCP 服务配置（适用于 Claude Desktop / Kiro）

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

选项 3：命令行

# Use lightweight model for development
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run start

先下载模型（推荐）：

# Set model in .env or via command line, then:
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run download-model

**注意：**更换模型需要重新为现有数据生成嵌入。模型会在首次使用时下载一次。

集成

Claude Desktop

使用 npx（推荐）

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

使用全局安装

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

使用本地构建版本

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

框架适配器

为与常用 AI 框架无缝集成而提供的官方适配器：

🦜 LangChain 适配器

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 适配器

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

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

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

**文档：**完整示例和 API 参考请参阅 adapters/README.md。

CLI 与 TUI

CLI 工具

功能完备的 CLI，支持所有操作：

# 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 <entity-id>

# 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

完整命令参考请查看 CLI 帮助：cozo-memory --help

TUI（终端用户界面）

由 Python Textual 提供支持、支持鼠标操作的交互式 TUI：

# Install Python dependencies (one-time)
pip install textual

# Launch TUI
npm run tui
# or directly:
cozo-memory-tui

TUI 功能：

• 🖱️ 完整的鼠标支持（点击按钮、滚动、选择输入项）
• ⌨️ 键盘快捷键（q=退出，h=帮助，r=刷新）
• 📊 所有操作均配有交互式菜单
• 🎨 支持颜色和动画的丰富终端界面

架构概览

graph TB
    Client[MCP Client<br/>Claude Desktop, etc.]
    Server[MCP Server<br/>FastMCP + Zod Schemas]
    Services[Memory Services]
    Embeddings[Embeddings<br/>ONNX Runtime]
    Search[Hybrid Search<br/>RRF Fusion]
    Cache[Semantic Cache<br/>L1 + L2]
    Inference[Inference Engine<br/>Multi-Strategy]
    DB[(CozoDB SQLite<br/>Relations + Validity<br/>HNSW Indices<br/>Datalog/Graph)]
    
    Client -->|stdio| Server
    Server --> Services
    Services --> Embeddings
    Services --> Search
    Services --> Cache
    Services --> Inference
    Services --> DB
    
    style Client fill:#e1f5ff,color:#000
    style Server fill:#fff4e1,color:#000
    style Services fill:#f0e1ff,color:#000
    style DB fill:#e1ffe1,color:#000

详细架构文档请参阅 docs/ARCHITECTURE.md

MCP 工具概览

接口精简为 5 个整合工具：

工具	用途	主要操作
mutate_memory	写入操作	create_entity、update_entity、delete_entity、add_observation、create_relation、transactions、sessions、tasks、update_observation、batch_delete、manage_tags、batch
query_memory	读取操作	search、advancedSearch、context、graph_rag、graph_walking、agentic_search、adaptive_retrieval、list_entities、get_entity_detail、get_session_context、list_sessions
analyze_graph	图分析	explore、communities、pagerank、betweenness、hits、shortest_path、semantic_walk
manage_system	维护	health、metrics、stats、export、import、cleanup、defrag、reflect、snapshots
edit_user_profile	用户偏好	编辑包含偏好和工作风格的全局用户资料

所有参数和示例的完整 API 参考请参阅 docs/API.md

故障排除

常见问题

首次启动耗时较长

• 首次启动时，嵌入模型下载需要 30–90 秒（Transformers 会加载约 500 MB 的文件）
• 这是正常现象，且只会发生一次
• 后续启动很快（< 2 秒）

由 LLM 驱动的操作需要 Ollama

• 以下操作会使用本地 LLM 进行智能处理：cleanup、reflect、summarize_communities、compact、agentic_search
• 从 https://ollama.ai 安装 Ollama
• 拉取所需模型：ollama pull demyagent-4b-i1:Q6_K（或你偏好的模型）
• 如果没有 Ollama，这些操作会回退到非 LLM 模式，或返回明确的错误
• 核心功能（CRUD、搜索、图、推理）无需任何 LLM 即可使用

Windows 特定说明

• 为确保最大兼容性，嵌入处理在 CPU 上进行
• 如果选择 RocksDB 后端，则需要 Visual C++ Redistributable

性能问题

• 重启后首次查询较慢（缓存未命中）
• 使用 health 操作检查缓存命中率
• 对于超过 100k 个实体的数据集，可考虑使用 RocksDB 后端

请参阅 docs/BENCHMARKS.md，了解性能优化技巧

文档

• docs/API.md - 完整的 MCP 工具参考，包含所有参数和示例
• docs/ARCHITECTURE.md - 系统架构、数据模型和技术细节
• docs/BENCHMARKS.md - 性能指标、评估结果和优化技巧
• docs/FEATURES.md - 详细的功能文档和使用示例
• docs/USER-PROFILING.md - 用户偏好画像和个性化
• CHANGELOG.md - 版本历史和发布说明
• CONTRIBUTING.md - 开发指南

开发

结构

• src/index.ts：MCP 服务 + 工具注册
• src/memory-service.ts：核心业务逻辑
• src/db-service.ts：数据库操作
• src/embedding-service.ts：嵌入管道 + 缓存
• src/hybrid-search.ts：搜索策略 + RRF
• src/inference-engine.ts：推理策略
• src/api_bridge.ts：Express API 桥接（可选）

脚本

npm run build        # TypeScript Build
npm run dev          # ts-node Start of MCP Server
npm run start        # Starts dist/index.js (stdio)
npm run bridge       # Build + Start of API Bridge
npm run benchmark    # Runs performance tests
npm run eval         # Runs evaluation suite

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

Apache 2.0 - 详情请参阅 LICENSE。

致谢

基于以下项目构建：

• CozoDB - 嵌入式图数据库
• ONNX Runtime - 本地嵌入生成
• Transformers.js - Xenova/bge-m3 模型
• FastMCP - MCP 服务框架

研究基础：

• GraphRAG-R1 (Yu 等人，WWW 2026) - 为自适应检索提供概念启发
• HopRAG (ACL 2025) - 为多跳推理提供概念启发
• T-GRAG (Li 等人，2025) - 为时序冲突消解提供概念启发
• FEEG Framework (Samuel 等人，2026) - 为查询意图分类提供概念启发
• Allan-Poe (arXiv:2511.00855) - 为动态融合提供概念启发