记忆印迹
    
用于AI代理的事件源存储系统。写路径中没有LLM——只有具有语义搜索的可靠剧集存储。
为什么选择Engram？
大多数AI存储系统通过在写入时执行实体提取来将写入可靠性与LLM可用性结合起来。Engram采用了一种不同的方法：首先可靠地存储事件，在语义上搜索它们，并将任何昂贵的派生结构（知识图、实体提取）推迟到可选的第二层。
结果： 写入永远不会失败，搜索速度很快，并且您可以获得一个没有运行时依赖关系的可移植二进制文件。
特性
- 三种搜索模式 --按意义（向量）、按精确单词（关键字）或同时按两者（混合）查找记忆
- 优雅的回退 --即使嵌入服务不可用，关键字搜索也能工作；混合动力车性能良好
- 快速查询 --DuckDB HNSW索引用于低于100ms的矢量搜索
- 零外部API --所有嵌入都是通过Ollama本地生成的
- 单个二进制 --可跨Linux、macOS和Windows移植
- MCP本地 --直接与Claude Desktop、Claude Code和Cursor集成
快速开始
先决条件
- 奥拉玛 使用嵌入模型在本地（或远程）运行
- 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拉动嵌入模型
ollama pull nomic-embed-text跑
启动服务器：
engram serveEngram在端口3490上启动并打印SSE端点URL。所有MCP客户端都连接到这个服务器——没有数据库锁定冲突。看 docs/mcp-integration.md 有关在macOS、Linux和Windows上作为后台服务运行的说明。
配置
通过环境变量进行配置：
| 变量 | 描述 | 默认值 |
|---|---|---|
DUCKDB_PATH | DuckDB数据库文件的路径 | ./engram.duckdb |
OLLAMA_URL | API终点 | http://localhost:11434 |
EMBEDDING_MODEL | 嵌入模型名称 | nomic-embed-text |
ENGRAM_PORT | 服务器端口 | 3490 |
ENGRAM_SERVER_URL | 服务器URL（由stdio代理使用） | http://localhost:3490 |
看 .env.example 对于模板。
MCP客户端集成
Engram通过模型上下文协议（MCP）与Claude Desktop、Claude Code和Cursor集成。
快速设置
- 启动服务器 （参见 后台服务文档 用于持久设置）：
engram serve- 连接您的客户。 大多数客户直接支持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/ # Ollama 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连接到服务器 - DuckDB VSS扩展用于向量相似性搜索（HNSW索引）
- 奥拉玛 用于本地嵌入生成（768维，
nomic-embed-text)
如需更深入地了解架构，请参阅 docs/architecture.md.
设计原则
- 写作永不失败 （如果数据库已启动）
- 写入路径中没有LLM --仅嵌入，这些是可重试的
- 事件日志是真相的来源 --其他一切都是派生的
- 简单多于聪明 --矢量搜索覆盖了80%的用例
- 便携的 --单个二进制、单个数据库文件
文档
测试
该项目包括单元和集成测试：
# Run all tests
just test
# Run with coverage
just test-coverage贡献
看 贡献.md 关于开发设置、代码风格以及如何提交pull请求。
许可证
麻省理工学院