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。