Engram

🚀 Engram

Engram是一个专为AI智能体设计的事件溯源内存系统。它在写入路径中不依赖大语言模型（LLM），仅专注于可靠的事件存储和语义搜索。

🚀 快速开始

前提条件

• 本地（或远程）运行带有嵌入模型的 Ollama。
• Go 1.25 及以上版本（仅在从源代码构建时需要）。

安装

选项A：下载预构建的二进制文件

从 发布页面 为你的平台下载：

# macOS/Linux：使其可执行
chmod +x engram-*
mv engram-* engram

选项B：从源代码构建

git clone https://github.com/OscillateLabsLLC/engram
cd engram

# 使用 just（推荐 — 从 https://github.com/casey/just 安装）
just setup    # 安装依赖项，拉取嵌入模型，构建

# 或者手动操作
go build -o engram ./cmd/engram/main.go

拉取嵌入模型

ollama pull nomic-embed-text

运行

export DUCKDB_PATH="./engram.duckdb"
export OLLAMA_URL="http://localhost:11434"
export EMBEDDING_MODEL="nomic-embed-text"

./engram

✨ 主要特性

• 语义搜索 — 使用向量相似度对结果进行相关性排序，而非按时间顺序。
• 优雅降级 — 即使嵌入服务不可用也能正常工作。
• 快速查询 — 使用 DuckDB HNSW 索引实现亚 100 毫秒的向量搜索。
• 零外部 API — 所有嵌入均通过 Ollama 在本地生成。
• 单二进制文件 — 可在 Linux、macOS 和 Windows 上移植。
• MCP 原生支持 — 直接与 Claude Desktop、Claude Code 和 Cursor 集成。

📚 详细文档

• MCP 集成指南 - 客户端设置、可用工具、故障排除。
• 部署指南 - Docker Compose、Kubernetes、生产部署。
• 架构 - 系统设计的技术深入剖析。

🔧 技术细节

架构

engram/
├── cmd/engram/          # 入口点
├── internal/
│   ├── db/              # DuckDB 操作 + VSS
│   ├── embedding/       # Ollama 客户端
│   ├── mcp/             # MCP 服务器实现
│   └── models/          # 数据模型
├── scripts/             # 构建和测试脚本
├── .github/workflows/   # CI/CD（构建 + 发布）
└── Dockerfile           # 容器镜像

• Go 服务使用官方 MCP SDK (mark3labs/mcp-go)。
• DuckDB 带有 VSS 扩展，用于向量相似度搜索（HNSW 索引）。
• Ollama 用于本地嵌入生成（768 维，nomic-embed-text）。
• stdio 传输用于 MCP 客户端集成。

设计原则

1. 写入永不失败（如果数据库正常运行）。
2. 写入路径中不使用 LLM — 仅使用可重试的嵌入。
3. 事件日志是事实来源 — 其他一切都是派生的。
4. 简单胜于复杂 — 向量搜索覆盖 80% 的用例。
5. 可移植性 — 单二进制文件，单数据库文件。

📦 安装指南

配置

通过环境变量进行配置：

请参阅 获取模板。

MCP 客户端集成

Engram 通过模型上下文协议（MCP）与 Claude Desktop、Claude Code 和 Cursor 集成。

快速设置（本地）

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "engram-memory": {
      "command": "/absolute/path/to/engram",
      "args": [],
      "env": {
        "DUCKDB_PATH": "/absolute/path/to/engram.duckdb",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}

⚠️ 重要提示

使用绝对路径。在 macOS 上，运行 realpath engram 以获取完整路径。

有关详细的集成说明、远程部署、可用的 MCP 工具和故障排除，请参阅 docs/mcp-integration.md。

Docker 与部署

快速开始（开发）

# macOS/Windows
just docker-up

# Linux
just docker-up-linux

有关包括 Docker Compose、Kubernetes 和生产配置的详细部署说明，请参阅 docs/deployment.md。

💻 使用示例

运行测试

# 运行所有测试
just test

# 运行并查看覆盖率
just test-coverage

📄 许可证

本项目采用 MIT 许可证。

有关开发设置、代码风格以及如何提交拉取请求，请参阅 CONTRIBUTING.md。