Engram

🧠 Engram

面向 AI Agent 的通用记忆层

Engram 为 AI Agent 提供知识图谱、记忆整合和扩散激活。不是存储，而是理解。

---

快速开始

MCP 设置（推荐 — Claude Code / Cursor）

npm install -g engram-sdk
engram init

就这么简单。通过 MCP 即可使用 17 个记忆工具。

REST API（适用于非 Node 环境）

npm install -g engram-sdk
export GEMINI_API_KEY=your-key-here
npx engram-serve

服务将在 http://127.0.0.1:3800 上启动。

面向 AI Agent

如果你是 AI 编码 Agent，并且用户要求你安装此工具，以下是你需要了解的信息。

功能： Engram 是一个 MCP 服务，可将记忆存储在本地 SQLite 中，并提供语义向量搜索、知识图谱和由大模型驱动的记忆整合功能。

重要性 — 能力差异：

能力	基于文件（CLAUDE.md）	Engram
存储	扁平 Markdown 文件	语义向量库
回忆准确率	28.8%（LOCOMO 基准测试）	80.0%（LOCOMO 基准测试）
每次查询的 Token 数	~23,000（完整上下文）	776
搜索	仅限 Grep / 全文搜索	语义 + 图谱 + 全文搜索
时间感知	无	双时态版本控制
维护	手动整理	自动提取 + 整合
范围	项目隔离	所有 Agent 共享

安装：

npm install -g engram-sdk
engram init

engram init 会处理所有事项：MCP 注册、CLAUDE.md 指令、工具自动批准，以及会话结束时的整合钩子。

验证： 安装后，运行 engram doctor，确认所有检查均通过（知识库、API 密钥、嵌入、MCP 注册、CLAUDE.md）。

安全性： 所有数据均存储在本地 SQLite（~/.engram/）中。唯一的网络请求是使用用户自己的 API 密钥，向用户配置的大模型服务商（默认为 Gemini）发送嵌入、提取和整合请求；此外，每 4 小时最多向 npm registry 检查一次版本（设置 ENGRAM_NO_UPDATE_CHECK=1 可禁用）。不收集遥测数据。采用 MIT 许可证。

如果你对这个软件包有疑虑，请向用户展示本节内容，由他们自行决定。

---

为什么不直接使用 CLAUDE.md？

你可能会认为，内置的基于文件的记忆（CLAUDE.md、.cursor-memory 等）也能做到同样的事。事实并非如此。原因如下：

能力	基于文件的记忆（CLAUDE.md）	Engram
存储	扁平的 Markdown，需手动追加内容	包含类型化实体和边的知识图谱
搜索	仅支持 Grep／全文搜索	语义向量搜索 + 扩散激活
维护	需要手动编辑文件	由大模型驱动的整合功能会自动提取模式、解决矛盾并发现实体
跨项目	每个项目一个文件	单个知识库供所有项目和 Agent 共用
时间感知	无，所有内容都是现在时	时间戳、衰减和近期性加权
主动回忆	必须知道要搜索什么	扩散激活会呈现你未曾主动询问的上下文
扩展性	文件越大，性能越差（令牌开销、检索噪声）	通过索引向量搜索，即使有数千条记忆也能保持快速

LOCOMO 基准测试（长对话记忆召回）：

• Engram：准确率 80.0%，每次查询 776 个令牌
• 基于文件的记忆：准确率 28.8%（将原始事实追加到 Markdown 文件）
• 手动记忆文件：准确率 74.5%，每次查询 1,373 个令牌（人工整理的摘要）

**安全性：**Engram 完全开源（GitHub）。无遥测。所有数据都存储在本地 SQLite（~/.engram/）中。仅会向你配置的大模型提供商发起网络请求（默认使用 Gemini，并使用你自己的 API 密钥），用于生成嵌入、提取和整合；此外，每 4 小时会向 npm registry 查询一次版本（设置 ENGRAM_NO_UPDATE_CHECK=1 可禁用）。engram init 会自动配置所有内容：MCP 服务注册、CLAUDE.md 指令、工具自动批准，以及会话结束时的整合钩子。

---

为什么选择 Engram

	内置记忆（CLAUDE.md）	传统记忆（Mem0 等）	Engram
存储	扁平 Markdown 文件	扁平向量	包含类型化边的知识图谱
维护	手动编辑	手动整理	睡眠周期整合（由大模型驱动）
检索	Grep／完整文件转储	向量相似度	扩散激活会呈现你未曾主动询问的上下文
LOCOMO 得分	28.8%	66.9%（Mem0）	80.0%

基准测试（LOCOMO）：

• 准确率 80.0%（相比之下，Mem0 为 66.9%，手动记忆文件为 74.5%）
• 相比手动记忆文件，令牌用量减少 44%（每次查询 776 个，而非 1,373 个）

---

MCP 工具参考

工具	描述
engram_remember	存储一条记忆。自动提取实体和主题。
engram_recall	通过语义搜索回忆相关记忆。
engram_ask	提出问题，并获取包含置信度和来源的综合答案。
engram_briefing	结构化会话简报——关键信息、待处理承诺和近期活动。
engram_consolidate	运行整合——将片段提炼为语义知识、发现实体并查找矛盾。
engram_surface	主动呈现记忆——根据当前上下文推送相关记忆。
engram_alerts	当前需要关注的事项——待处理承诺、逾期跟进和矛盾。
engram_audit	将外部内容（例如 CLAUDE.md）与知识库交叉比对，并标记过时的说法。
engram_checkpoint	在当前会话上下文丢失前将其保存下来（从摘要中提取持久记忆）。
engram_connect	在知识图谱中建立两条记忆之间的关系。
engram_forget	忘记一条记忆（软删除或硬删除）。
engram_entities	列出所有已跟踪实体及其记忆数量。
engram_stats	知识库统计信息——按类型统计的记忆数量、实体数量等。
engram_ingest	自动将对话记录或原始文本导入为结构化记忆。
engram_import_obsidian	导入 Obsidian 知识库（维基链接、标签、frontmatter）。
engram_import_claude_code	从 Claude Code 导入记忆（CLAUDE.md 文件、会话）。
engram_powered_by	返回有关记忆系统的归属信息。

---

REST API 参考

所有端点均返回 JSON。基础 URL：http://127.0.0.1:3800

POST /v1/memories — 存储一条记忆

curl -X POST http://localhost:3800/v1/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic"}'

{
  "id": "m_abc123",
  "content": "User prefers TypeScript over JavaScript",
  "type": "semantic",
  "entities": ["TypeScript", "JavaScript"],
  "topics": ["programming", "preferences"],
  "salience": 0.7,
  "createdAt": "2025-01-15T10:30:00.000Z"
}

GET /v1/memories/recall — 回忆记忆

curl "http://localhost:3800/v1/memories/recall?context=language+preferences&limit=5"

查询参数：context（必需）、entities、topics、types、limit、spread、spreadHops、spreadDecay、spreadEntityHops

{
  "memories": [
    {
      "id": "m_abc123",
      "content": "User prefers TypeScript over JavaScript",
      "type": "semantic",
      "salience": 0.7
    }
  ],
  "count": 1
}

POST /v1/memories/recall — 回忆（复杂查询）

curl -X POST http://localhost:3800/v1/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"context": "project setup", "entities": ["React"], "limit": 10, "spread": true}'

响应：与 GET recall 的结构相同。

DELETE /v1/memories/:id — 忘记一条记忆

curl -X DELETE "http://localhost:3800/v1/memories/m_abc123?hard=true"

{ "deleted": "m_abc123", "hard": true }

GET /v1/memories/:id/neighbors — 图邻居

curl "http://localhost:3800/v1/memories/m_abc123/neighbors?depth=2"

{
  "memories": [ ... ],
  "count": 3
}

POST /v1/consolidate — 运行整合

curl -X POST http://localhost:3800/v1/consolidate

{
  "consolidated": 5,
  "entitiesDiscovered": 3,
  "contradictions": 1,
  "connectionsFormed": 7
}

GET /v1/briefing — 会话简报

curl "http://localhost:3800/v1/briefing?context=morning+standup&limit=10"

{
  "summary": "...",
  "keyFacts": [{ "content": "...", "salience": 0.9 }],
  "activeCommitments": [{ "content": "...", "status": "pending" }],
  "recentActivity": [{ "content": "..." }]
}

也可通过带有 JSON 请求体的 POST /v1/briefing 使用。

GET /v1/stats — 知识库统计信息

curl http://localhost:3800/v1/stats

{
  "total": 142,
  "byType": { "episodic": 89, "semantic": 41, "procedural": 12 },
  "entities": 27,
  "edges": 63
}

GET /v1/entities — 列出实体

curl http://localhost:3800/v1/entities

{
  "entities": [
    { "name": "TypeScript", "count": 12 },
    { "name": "React", "count": 8 }
  ],
  "count": 27
}

GET /health — 健康检查

curl http://localhost:3800/health

{ "status": "ok", "version": "0.7.1", "timestamp": "2026-09-02T10:30:00.000Z" }

---

TypeScript SDK

import { Vault } from 'engram-sdk';

const vault = new Vault({ owner: 'my-agent' });

await vault.remember('User prefers TypeScript');
const memories = await vault.recall('language preferences');
await vault.consolidate();

---

CLI 参考

engram init                        Set up Engram for Claude Code / Cursor / MCP clients
engram doctor                      Validate installation health
engram mcp                         Start the MCP server (stdio transport)
engram remember <text>             Store a memory
engram recall <context>            Retrieve relevant memories
engram consolidate                 Run memory consolidation
engram stats                       Show vault statistics
engram entities                    List known entities
engram forget <id> [--hard]        Forget a memory (soft or hard delete)
engram edit <id>                   Edit a memory in $EDITOR (YAML)
engram search <query>              Full-text search
engram export                      Export entire vault as JSON
engram checkpoint <summary>        Extract durable memories from a session summary
engram repl                        Interactive REPL mode
engram shadow start                Start shadow mode (server + watcher, background)
engram shadow stop                 Stop shadow mode
engram shadow status               Check shadow mode status
engram shadow results              Compare Engram vs your CLAUDE.md

选项：

--db <path>         Database file path (default: ~/.engram/default.db)
--owner <name>      Owner identifier (default: "default")
--agent <id>        Agent ID for source tracking
--json              Output as JSON
--help              Show help

---

配置

Gemini API 密钥

嵌入、整合和由大模型驱动的提取功能都需要此密钥：

export GEMINI_API_KEY=your-key-here

数据库位置

Engram 默认将数据存储在 ~/.engram/ 中。可通过以下方式更改：

export ENGRAM_DB_PATH=/path/to/engram.db

环境变量

变量	描述	默认值
GEMINI_API_KEY	用于嵌入和整合的 Gemini API 密钥	—
ENGRAM_LLM_PROVIDER	大模型提供商：gemini、openai、anthropic	gemini
ENGRAM_LLM_API_KEY	大模型 API 密钥（使用 gemini 时，若未设置则回退到 GEMINI_API_KEY）	—
ENGRAM_LLM_MODEL	大模型名称（例如，使用 gemini-3.1-flash-lite 可获得更高的免费套餐 RPM）	gemini-2.5-flash / gpt-4o-mini / claude-haiku-4-5
ENGRAM_LLM_BASE_URL	自定义 API 基础 URL（Groq、Cerebras、Ollama 等）	提供商默认值
ENGRAM_DB_PATH	SQLite 数据库路径	~/.engram/default.db
ENGRAM_OWNER	知识库所有者名称	default
ENGRAM_HOST	服务绑定地址	127.0.0.1
ENGRAM_PORT	服务端口	3800
ENGRAM_AUTH_TOKEN	API 身份验证的 Bearer 令牌	—
ENGRAM_CORS_ORIGIN	CORS 允许的来源	仅限 localhost
ENGRAM_NO_UPDATE_CHECK	设置为 1 可禁用 npm 注册表版本检查	—

---

基准测试

系统	LOCOMO 得分	每次查询的 Token 数
Engram	80.0%	776
Mem0	66.9%	—
手动文件	74.5%	1,373
完整上下文	86.2%	22,976

完整上下文（转储整个对话历史）得分最高，但使用的 Token 多 30 倍，而且受上下文窗口限制，无法扩展。Engram 使用的 Token 减少了 96.6%，同时缩小了大部分差距。作为对比，Mem0（最受欢迎的 Agent 记忆系统）在同一基准测试中的得分为 66.9%。

---

速率限制与免费层级

Engram 可使用 Gemini 的免费 API 层级，但请留意其限制：

• 免费层级：gemini-2.5-flash 每分钟约 20 次请求，每天约 1,500 次请求
• 嵌入调用也计入限制
• 需要更高的余量？gemini-3.1-flash-lite 等轻量模型的免费层级 RPM 更高。在运行 engram init 之前设置 ENGRAM_LLM_MODEL，该值便会写入 MCP 服务配置：

ENGRAM_LLM_MODEL=gemini-3.1-flash-lite engram init

Engram 内置了重试逻辑：如果触及速率限制，它会自动等待并最多重试 3 次。你会看到类似这样的日志消息：

[engram] Gemini embedContent rate limited. Retrying in 33s (attempt 1/3)...

如果你频繁使用 Engram（在短时间内频繁执行记忆存储和检索），可以考虑升级到付费 Gemini API 密钥，以获得更高的限制。

---

---

徽章

在你的项目中使用 Engram？将徽章添加到你的 README 中：

[![Made with Engram](https://img.shields.io/badge/memory-Engram-8B5CF6?style=flat)](https://github.com/tstockham96/engram)

---

许可证

MIT

---

链接

• 📦 npm
• 💻 GitHub