AI导哈

AI代理记忆系统

Engram是一个为AI代理设计的基于事件的记忆存储系统，提供可靠的记忆存储和语义搜索功能，无需依赖LLM写入路径。

  • by OscillateLabsLLC
  • Go
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 OscillateLabsLLC/engram

使用说明

记忆痕迹

用于AI代理的事件源存储系统。写路径中没有LLM——只有具有语义搜索的可靠剧集存储。

📖 查看文档

为什么选择Engram？

大多数AI存储系统通过在写入时执行实体提取来将写入可靠性与LLM可用性结合起来。Engram采用了一种不同的方法：首先可靠地存储事件，在语义上搜索它们，并将任何昂贵的派生结构（知识图、实体提取）推迟到可选的第二层。

结果： 写入永远不会失败，搜索速度很快，并且您可以获得一个没有运行时依赖关系的可移植二进制文件。

特性

  • 三种搜索模式 --按意义（向量）、按精确单词（关键字）或同时按两者（混合）查找记忆
  • 优雅的回退 --即使嵌入服务不可用，关键字搜索也能工作；混合动力车性能良好
  • 快速查询 --DuckDB HNSW索引用于低于100ms的矢量搜索
  • 带上你自己的嵌入物 --适用于任何与OpenAI兼容的端点：LM Studio、Ollama、llama.cpp或托管提供商
  • 单个二进制 --可跨Linux、macOS和Windows移植
  • MCP本地 --直接与Claude Desktop、Claude Code和Cursor集成

快速开始

先决条件

  • 具有768维嵌入模型的OpenAI兼容嵌入服务器（例如。， nomic-embed-text). LM Studio 和 奥拉玛 两者都可以在本地或远程开箱即用。
  • 1.25+（仅当从源代码构建时）

安装

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

从下载 发布页面 对于您的平台：

平台 二进制
macOS（苹果硅） engram-darwin-arm64
macOS（英特尔） engram-darwin-amd64
Linux（x86_64） engram-linux-amd64
Linux（ARM64） engram-linux-arm64
窗户 engram-windows-amd64.exe 
# macOS/Linux: make it executable
chmod +x engram-*
mv engram-* engram

选项B：从源代码构建

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

# Using just (recommended — install from https://github.com/casey/just)
just setup    # install deps, pull embedding model, build

# Or manually
go build -o engram ./cmd/engram/main.go

获取嵌入模型

# LM Studio
lms get text-embedding-nomic-embed-text-v1.5

# Ollama
ollama pull nomic-embed-text

跑

启动服务器：

engram serve

Engram在端口3490上启动并打印SSE端点URL。所有MCP客户端都连接到这个服务器——没有数据库锁定冲突。看 docs/mcp-integration.md 有关在macOS、Linux和Windows上作为后台服务运行的说明。

配置

通过环境变量进行配置：

变量 描述 默认值
DUCKDB_PATH DuckDB数据库文件的路径 ./engram.duckdb
EMBEDDING_URL OpenAI兼容的嵌入端点 http://localhost:11434
EMBEDDING_MODEL 嵌入模型名称 nomic-embed-text
EMBEDDING_API_KEY 嵌入端点的承载令牌（如果需要） （无）
ENGRAM_PORT 服务器端口 3490
ENGRAM_SERVER_URL 服务器URL（由stdio代理使用） http://localhost:3490

EMBEDDING_URL 接受裸主机(http://localhost:11434一 /v1 基地(http://localhost:1234/v1)，或一个完整的 /v1/embeddings endpoint——Engram将其标准化。 OLLAMA_URL 仍然被视为已弃用的别名 EMBEDDING_URL.

示例：

# LM Studio
EMBEDDING_URL=http://localhost:1234/v1 EMBEDDING_MODEL=text-embedding-nomic-embed-text-v1.5 engram serve

# Ollama (the default)
EMBEDDING_URL=http://localhost:11434 EMBEDDING_MODEL=nomic-embed-text engram serve

注： Engram的模式存储768维向量，因此选择768维的嵌入模型（Nomic家族适合）。

看 .env.example 对于模板。

切换嵌入模型

来自不同模型的嵌入存在于不同的向量空间中——混合它们会悄悄地降低相似性得分。Engram记录哪个模型生成了每个存储的向量，当存储的嵌入与配置的模型不匹配时，在启动时发出警告，并可以在适当的位置重新生成它们：

# Refresh stale embeddings (missing, or produced by a different model)
curl -X POST http://localhost:3490/api/v1/admin/reembed

# Re-embed everything regardless of provenance
curl -X POST http://localhost:3490/api/v1/admin/reembed -d '{"force": true}'

# Check progress and staleness counts
curl http://localhost:3490/api/v1/admin/reembed

该作业在服务器内异步运行，只接触派生数据（剧集内容永远不会被修改），并且可以安全地重新运行——任何失败的都会在下一次重试。这也是您在嵌入服务器关闭时回填所写剧集的方式。

MCP客户端集成

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

快速设置

  1. 启动服务器 （参见 后台服务文档 用于持久设置）：

    engram serve

  2. 连接您的客户。 大多数客户直接支持SSE：

    光标 (.cursor/mcp.json):

    {
  "mcpServers": {
    "engram-memory": {
      "url": "http://localhost:3490/mcp/sse"
    }
  }
}

    克劳德桌面版 （stdio代理，适用于需要stdio的客户端）：

    {
  "mcpServers": {
    "engram-memory": {
      "command": "/absolute/path/to/engram",
      "args": ["stdio"],
      "env": {
        "ENGRAM_SERVER_URL": "http://localhost:3490"
      }
    }
  }
}

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

Docker和部署

快速启动（开发）

# macOS/Windows
just docker-up

# Linux
just docker-up-linux

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

清理模式

特工们通过以下方式清理陈旧的记忆 update_episode --印痕故意不暴露 delete_episode MCP工具，因为永久删除是一种故意的人类行为，而不是代理应该自主完成的事情。

软删除（可逆）

集 expired_at 到过去的时间戳。该事件在默认搜索中隐藏，但仍保留在存储中——稍后通过清除将其恢复 expired_at.

{"tool": "update_episode", "id": "...", "expired_at": "2020-01-01T00:00:00Z"}

降级（可见但已过滤）

替换剧集的标签，以包含类似的标记 deprecated 或 low-confidence。该事件会保留在搜索结果中，因此不会丢失任何内容，但调用者可以在查询时进行筛选。

{"tool": "update_episode", "id": "...", "tags": ["deprecated", "original-topic"]}

计划到期

集 expired_at 转换为未来的时间戳——在此时间之后，该事件将从默认搜索中消失，无需进一步操作。

建筑

engram/
├── cmd/engram/          # Entry point (serve / stdio subcommands)
├── internal/
│   ├── api/             # HTTP + MCP SSE server
│   ├── db/              # DuckDB operations + VSS
│   ├── embedding/       # OpenAI-compatible embeddings client
│   ├── mcp/             # MCP tool definitions
│   ├── models/          # Data models
│   └── proxy/           # stdio-to-SSE proxy
├── scripts/             # Build and test scripts
├── .github/workflows/   # CI/CD (build + release)
└── Dockerfile           # Container image
  • 服务器优先: engram serve 独家拥有DuckDB，通过SSE+REST API公开MCP
  • 精简stdio代理: engram stdio 为需要stdio的客户端（例如Claude Desktop）将stdin/stdout连接到服务器
  • 鸭数据库 VSS扩展用于向量相似性搜索（HNSW索引）
  • OpenAI兼容嵌入 --LM Studio、Ollama、llama.cpp或托管提供商（768维，例如。 nomic-embed-text)

如需更深入地了解架构，请参阅 docs/architecture.md.

设计原则

  1. 写作永不失败 （如果数据库已启动）
  2. 写入路径中没有LLM --仅嵌入，这些是可重试的
  3. 事件日志是真相的来源 --其他一切都是派生的
  4. 简单多于聪明 --矢量搜索覆盖了80%的用例
  5. 便携的 --单个二进制、单个数据库文件

文档

测试

该项目包括单元和集成测试：

# Run all tests
just test

# Run with coverage
just test-coverage

贡献

看 贡献.md 关于开发设置、代码风格以及如何提交pull请求。

许可证

麻省理工学院

相关 MCP