Engram

---

什么是 Engram？

Engram 为任何 AI 模型提供类似人类的记忆，可在不同会话、系统和重启后持续保留。只需连接一次，你使用的每个 AI——Claude Code、Ollama 或任何自定义集成——都能共享同一个不断扩展的大脑。

大多数 AI 工具会在会话结束时忘记所有内容。Engram 通过充当通用记忆后端解决了这个问题：它存储 AI 学到的内容，在合适的时机检索恰当的记忆，并将其作为上下文提供——这一切都会自动完成。

┌─ You tell Claude Code about your stack  ──→  stored as semantic memory
└─ Next day, different tool, new session  ──→  Engram recalls it automatically

---

功能

功能	描述
3 种记忆类型	情景记忆（事件）、语义记忆（事实 + 知识图谱）、程序记忆（触发条件→行动模式）
7 步召回流程	嵌入 → 向量搜索 → 图谱扩展 → 评分 → 排序 → 截断 → 记录
记忆衰减与 GC	艾宾浩斯遗忘曲线、自动归档过时记忆、将情景记忆整合为语义记忆
记忆反思	AI 驱动的洞察引擎——通过 MCP 连接的 AI 会对你的记忆进行推理，发现模式、知识缺口、趋势和矛盾。Engram 不运行自己的大模型——无需 API 密钥，也不会进行外部调用。
Atlas 仪表板	地图、召回、审查、时间线、洞察和设置；支持浅色/深色主题及 ⌘K 命令面板
可选命名空间	默认禁用；可按项目/Agent 启用筛选或严格隔离
矛盾检测	自动检测相互冲突的记忆，提供 5 种解决策略（keep_newest/oldest/important/both/manual）
嵌入可升级	更换嵌入模型、将模型 ID 与向量一同存储、批量重新嵌入流程
流式召回	SSE 端点——先返回高置信度记忆，稍后补充图谱扩展结果
索引持久化	将向量索引保存/加载到磁盘，以便快速启动（提速 27-37 倍）
CLI 工具	可在终端中使用 engram store/search/recall/stats/forget/export/import/reflections/cloud
导入/导出	通过 CLI 或 API，以 JSON 或 NDJSON 格式进行完整备份和恢复
Webhook	让外部系统订阅记忆事件（存储、遗忘、衰减、整合、矛盾、反思）
标签与集合	标签云、按标签筛选、基于前缀的集合（例如 project:alpha）
插件系统	7 个生命周期钩子（onStore、onRecall、onForget、onDecay、onReflect、onStartup、onShutdown）
重要性衰减	根据来源设置默认重要性、未使用记忆每日衰减、针对 AI 客户端的保护规则
内联编辑与批量操作	通过 API 和仪表板 PATCH 单条记忆，或批量添加标签/归档
可观测性	调试端点、评分明细、/docs 中的 Swagger UI

---

工作原理

每次连接到 Engram 的 AI 收到查询时：

1. 将查询嵌入为 384 维语义向量（在本地完成——无需 API，也不产生费用）
2. 搜索向量索引，查找相似的过往记忆
3. 扩展知识图谱，检索相关概念
4. 为候选记忆评分：综合语义相似度、时效性、重要性和访问频率
5. 检查是否与现有记忆存在矛盾
6. 将整理好的上下文注入 AI 的提示词

AI 会结合它曾经学到的一切来作答。交流结束后，响应会作为新记忆存储起来——大脑持续成长。

---

记忆模型

类型	存储内容	示例
情景记忆	事件、对话、带时间戳的交互	“用户在 2026-03-15 询问部署事宜”
语义记忆	事实、知识、概念和知识图谱	concept: TypeScript → “JavaScript 的强类型超集”
程序记忆	模式、技能、触发条件→操作规则	“用户询问数据库迁移时 → 使用 drizzle-kit generate”
工作记忆	为查询动态整理的上下文	（在查询时整理，不会存储）

---

集成

Claude Code    ──MCP──────────→ ┐
Claude Desktop ──extension────→ │  Engram  →  SQLite
Ollama         ──proxy────────→ │  REST :4901
Any app        ──REST─────────→ │
CLI            ──direct───────→ ┘

集成	方式	说明
Claude Code	MCP（24 个原生工具）	store_memory、recall_context、request_reflection、…
Claude Desktop	一键式桌面扩展	Smithery 或从发行版获取 .mcpb
Ollama	透明 HTTP 代理	将客户端指向 :11435，而不是 :11434
任何应用	直接调用 REST API	POST /api/recall + POST /api/memory
终端	命令行	engram recall "what was the last decision?"

---

快速开始

一条命令安装

对于 Claude Code，请选择推荐的插件，或者使用 engram setup 配置 MCP 和钩子，不要同时使用两者。

# Memory for your AI client — npx-based MCP config, no clone/build
npx -y @engram-ai-memory/cli setup --npx

# Optional: REST API + Atlas dashboard on :4901 (the wizard clones and builds the server)
npm i -g @engram-ai-memory/cli
engram setup
engram start

第一条命令就是 MCP 客户端所需的一切。服务运行后，打开 http://localhost:4901 查看仪表板，打开 /docs 查看 Swagger UI。

命令行命令

engram setup                 # Clone, build, install the CLI globally, wire up MCP
engram setup --npx           # Fast setup — npx-based MCP config, no clone/build
engram setup --source cursor # Also picks WHICH client config file to write (see below)
engram init                  # Generate AI memory instructions (CLAUDE.md, .cursorrules, etc.)
engram init --client cursor  # Generate instructions for a specific client
engram update                # Pull, rebuild, re-link the CLI, restart the server
engram update --force        # Update even with local repo changes (stashed, or kept on a backup branch)
engram update --no-restart   # Update without restarting the server
engram start                 # Start the server (detached)
engram start --foreground    # Run it in this terminal instead
engram stop                  # Stop the server — waits for it to actually exit
engram doctor                # Health checks; exits 1 when it finds something
engram status                # Server status + memory count
engram configure show        # Print the current config
engram configure set <k> <v> # Change one setting
engram configure path        # Print the config file path
engram cloud connect <url>   # Configure multi-device sync against Postgres
engram cloud status          # Sync state, last sync, pending pushes
engram cloud sync            # Run one push + pull now
engram cloud encrypt         # Turn on end-to-end encryption (prompts for the passphrase)
engram cloud devices         # This device's sync identity
engram cloud disconnect      # Stop syncing; the local database is untouched

engram setup --source <client> 会同时选择写入已存储记忆的标识符以及要写入的配置文件：claude-code → ~/.claude.json，cursor → ~/.cursor/mcp.json，windsurf → ~/.codeium/windsurf/mcp_config.json。任何其他值（包括默认值）都不会注册任何内容，而是打印 JSON 配置块供你自行粘贴。它绝不会写入 ~/.mcp.json；没有 MCP 客户端会读取该路径。

engram stop、engram doctor 和 engram update 会通过退出码报告失败，因此可用于脚本：stop 最多等待进程退出 10 s；如果进程可能仍在运行，则返回 1（并且不会向不拥有该端口的 PID 发送信号）；如果任一检查失败，doctor 会返回 1；如果代码仓库已更新，但构建、全局 CLI 刷新或重启未能完成，update 会返回 1。update 除了检查 git 状态，还会检查构建标记，因此升级后的首次运行总会重新构建，不会因过时的 dist/ 而报告“已是最新版本”。

手动安装（替代方式）

git clone https://github.com/ayvazyan10/engram
cd engram
pnpm install
pnpm turbo run build
node apps/server/dist/index.js

或者使用 PM2 在后台持续运行：

pnpm turbo run build
pm2 start ecosystem.config.cjs
pm2 logs engram

存储第一条记忆

curl -X POST http://localhost:4901/api/memory \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers TypeScript over JavaScript", "type": "semantic", "concept": "preferences"}'

询问大脑

curl -X POST http://localhost:4901/api/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "What language does the user prefer?"}'

---

命令行

全局安装命令行工具，以便在终端中使用：

npm i -g @engram-ai-memory/cli

# Store a memory
engram store "User prefers TypeScript" --type semantic --importance 0.8

# Search
engram search "TypeScript" --top 5

# Recall context (pipeable)
engram recall "what languages does the user prefer?" --raw

# Stats
engram stats

# Export/import
engram export > backup.json
engram import < backup.json

# Forget
engram forget a1b2c3d4-...

# Reflection (AI-driven — runs on the AI connected via MCP)
engram reflect-status                   # show whether a reflection cycle is due
engram reflections --type pattern       # list stored pattern insights

反思无需配置大模型

Engram 本身绝不会调用模型。需要执行反思周期时，通过 MCP 连接的 AI 会使用 request_reflection → store_reflection 进行推理。无需配置服务提供商、模型或 API 密钥。

将 ENGRAM_DB_PATH 设置为数据库文件的路径。

---

MCP 设置（Claude Code、Cursor、Windsurf、Cline）

在任何兼容 MCP 的 AI 客户端中将 Engram 添加为原生工具——无需 API 调用，也无需包装器。

将以下配置添加到客户端读取的文件中：

客户端	配置文件
Claude Code（用户范围）	~/.claude.json
Claude Code（项目范围）	项目根目录中的 .mcp.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

engram setup --source <client> 会为你写入正确的配置。其他客户端会读取各自的文件——请查阅其文档，并将相同的配置块粘贴到相应文件中。

{
  "mcpServers": {
    "engram": {
      "command": "npx",
      "args": ["-y", "-p", "@engram-ai-memory/mcp@latest", "engram-mcp"],
      "env": {
        "ENGRAM_DB_PATH": "~/.engram/engram.db",
        "ENGRAM_SOURCE": "claude-code"
      }
    }
  }
}

注意： 请勿将 mcpServers 放入 ~/.claude/settings.json——该文件仅用于 Claude Code 设置。MCP 服务应放在 ~/.claude.json（用户范围）或 .mcp.json（项目范围）中。

如果你通过 engram setup 安装，也可以改为指向本地构建：

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["/home/you/.engram/repo/packages/mcp/dist/server.js"],
      "env": {
        "ENGRAM_DB_PATH": "~/.engram/engram.db",
        "ENGRAM_SOURCE": "claude-code"
      }
    }
  }
}

重启 AI 客户端。现在可以使用 24 个工具：

类别	工具
记忆	store_memory, search_memory, recall_context, add_knowledge, forget
统计与健康状态	memory_stats, index_status, embedding_status
生命周期	decay_sweep, decay_policy, re_embed
矛盾	check_contradictions, resolve_contradiction
反思	request_reflection, store_reflection, get_reflections
提炼	get_distill_tasks, complete_distill
标签	list_tags, tag_memory
Webhook	webhook_subscribe, webhook_list
插件	plugin_list

自动存储对话（可选）

添加 Claude Code 钩子，在会话结束时自动将对话摘要保存到 engram：

# Copy the hook script
cp scripts/claude-code-hook.sh ~/.claude/hooks/engram-session-end.sh
chmod +x ~/.claude/hooks/engram-session-end.sh

添加到 ~/.claude/settings.json：

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/engram-session-end.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

现在每个会话都会自动将摘要存储到 engram——无需手动操作，记忆库也会不断扩展。

存储的会话会标记为 pending-distill。连接到 Engram 的 AI 会调用 get_distill_tasks，自行提取持久事实（Engram 不运行大模型，也不需要 API 密钥），然后调用 complete_distill，存储这些事实并归档原始会话。SessionStart 会提醒 AI 处理待提炼的会话。

---

Claude Desktop 扩展（一键安装）

将 Engram 添加到 Claude Desktop 的最快方式——无需手动编辑 JSON。

通过 Smithery

前往 smithery.ai/skills/ayvazyan10/engram，点击 安装，可选择设置数据库路径和命名空间，Smithery 会自动配置 Claude Desktop。

通过 .mcpb Desktop Extension

从 GitHub Releases 下载 engram-mcp.mcpb，并在 Claude Desktop 中打开（文件 → 打开扩展）。此安装包会在首次启动时自动将 @engram-ai-memory/mcp 安装到 ~/.engram/mcp/——无需设置。

引导流程的工作原理： 首次运行时，.mcpb 安装包会通过 npm 将 @engram-ai-memory/mcp@<version> 安装到 ~/.engram/mcp/。标记文件可防止后续启动时重复安装。随后，Claude Desktop 中即可使用全部 24 个 MCP 工具。

---

软件包

软件包	描述	npm
@engram-ai-memory/core	大脑——记忆引擎、嵌入、图谱、检索、衰减、反思
@engram-ai-memory/mcp	MCP 服务——为 Claude Code 和兼容 MCP 的客户端提供 24 个工具
@engram-ai-memory/cli	CLI——在终端中存储、搜索、回忆、反思、查看统计、导出和导入
@engram-ai-memory/server	Fastify REST API + Socket.io WebSocket（53 个端点）	—
@engram-ai-memory/web	Atlas 仪表板——地图、回忆、审阅、时间线、洞察、设置	—
@engram-ai-memory/vis	力导向布局 + 动画辅助工具
@engram-ai-memory/adapter-ollama	透明的 Ollama 记忆代理（:11435）	—

---

环境变量

变量	默认值	说明
PORT	4901	API 服务端口
HOST	127.0.0.1	绑定地址——默认仅限回环地址
ENGRAM_SOURCE	mcp-client	客户端标识符（例如 claude-code、cursor、windsurf）
ENGRAM_DB_PATH	~/.engram/engram.db	SQLite 数据库路径。留空表示使用默认值；~ 和 ~/x 会展开
ENGRAM_NAMESPACE_MODE	project	命名空间行为：project、none、filter 或 isolated
ENGRAM_NAMESPACE	(无)	在模式为 filter 或 isolated 时使用的命名空间值；会覆盖 project 检测结果
ENGRAM_INDEX_PATH	{dbPath}.index	持久化向量索引路径
ENGRAM_EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	覆盖嵌入模型
ENGRAM_DECAY_INTERVAL	3600000	自动衰减扫描间隔（毫秒）
ENGRAM_DECAY_THRESHOLD	0.05	低于此保留分数的记忆将被归档
ENGRAM_ALLOWED_ORIGINS	本地主机仪表板来源	允许调用 API 的浏览器来源（CORS + WebSocket），以逗号分隔。非浏览器客户端（命令行、MCP、curl）不受影响。
ENGRAM_API_KEY	(无)	设置后，除 /api/health 外的所有 API 路由都必须通过 X-API-Key 或 Authorization: Bearer 提供此密钥。未设置 = 开放访问（本地优先的默认设置）。若已设置但值为空，则会中止启动，而不是静默禁用身份验证。
ENGRAM_ALLOWED_HOSTS	(空)	/api/* 的 Host 标头中允许的主机名（防范 DNS 重绑定）。IP 字面量和 localhost 始终通过；任何通过名称访问的主机——反向代理、Docker 服务名等——都必须列入此项。* 可禁用检查。
ENGRAM_RATE_LIMIT_MAX	1000	global 层级每个时间窗口内的请求数。另有 ENGRAM_RATE_LIMIT_HEAVY_MAX（300）、ENGRAM_RATE_LIMIT_WHOLE_STORE_MAX（30）、ENGRAM_RATE_LIMIT_WINDOW_MS（60000）、ENGRAM_RATE_LIMIT_DISABLED。
ENGRAM_CSP	(内置策略)	覆盖每个响应发送的 Content-Security-Policy，或设为 off 以不发送。
ENGRAM_WEBHOOK_ALLOW_PRIVATE	false	允许向回环地址或私有地址发送 webhook。默认拒绝以防止 SSRF；如果 webhook 消费端位于 localhost 或私有网络，请设为 true。
ENGRAM_SYNC_URL	(无)	用于多设备同步的 PostgreSQL 连接字符串。未设置 = 禁用同步。参见 Cloud Sync。
ENGRAM_SYNC_MODE	auto	同步行为：auto（按间隔并通过防抖在后台同步）、manual（仅显式同步）、off。
ENGRAM_SYNC_INTERVAL	30000	后台同步间隔（毫秒；仅限自动模式）。
ENGRAM_SYNC_ALLOW_UNENCRYPTED	false	允许使用非 TLS 的 PostgreSQL 连接。仅用于本地开发——生产环境应始终使用 sslmode=require。
ENGRAM_SYNC_ENCRYPTION_KEY	(无)	用于对同步数据进行端到端加密的密码短语。未设置 = 数据以明文形式传至 Postgres。参见 Cloud Sync。
OLLAMA_PROXY_PORT	11435	Ollama 代理监听端口
ENGRAM_PROXY_HOST	127.0.0.1	Ollama 代理绑定地址——默认仅限回环地址。代理没有身份验证，因此绑定范围更广会让网络上的任何对等方都能获得一个可驱动你 GPU 的端点。
ENGRAM_MAX_BODY_BYTES	10485760	代理请求正文的大小上限；超过后代理会返回 413。
ENGRAM_TOOL_RETRY	true	工具调用失败时，自动附带一条指令重试一次（代理）

project 是默认值：在 git 仓库中，MCP 服务和钩子会将范围限定为 git 顶层目录的绝对路径，并读取该项目的记忆以及全局记忆；在仓库外，它们会使用共享池。filter 将范围限定为 ENGRAM_NAMESPACE，而 isolated 与 ENGRAM_NAMESPACE 配合使用时会形成固定边界，拒绝覆盖设置和跨命名空间查询。REST 服务和仪表板始终以 none 模式运行，可以查看所有项目。现有记忆的 namespace 为 NULL，并保持全局可见。 这是一份摘要。docs/CONFIGURATION.md 列出了完整配置项，包括 Security 下的所有内容。请注意，engram start 会根据 ~/.engram/config.json 设置服务的运行环境，因此它管理的 shell 变量会被覆盖——请参阅 CLI section。

---

端口

服务	端口	用途
Engram API	4901	REST + WebSocket + Swagger UI
Dashboard	4901	Atlas 仪表盘（由 API 服务提供）
Dashboard (Docker)	4902	独立的仪表盘容器，可选
Ollama Proxy	11435	记忆注入代理 → Ollama

docker compose 仅在 loopback 地址上发布全部三个端口，此外还有用于同步测试的 Postgres 端口 5432。若要有意公开 API，必须设置 ENGRAM_API_KEY、将公共主机名添加到 ENGRAM_ALLOWED_HOSTS，然后才能更改发布地址。

所有端口都在 49xx 范围内，以避免与常见开发服务（3000、5173、8080 等）冲突。

---

在线演示

# Load demo memories with knowledge graph connections
cd packages/core && npx tsx scripts/demo.ts

# Open the Atlas dashboard
# → http://localhost:4901

Atlas 视图： 地图 · 回忆 · 审阅 · 时间线 · 洞察 · 设置

在地图上探索记忆，其中包含命名区域、「意义 / 故障 / 时间」视角和搜索图钉。视图切换器还提供四个按需加载的视图，可通过 #/?view=sky|landscape|river|pulse 访问：Sky 是按意义和时间排列的 WebGL 夜空；Landscape 是记忆保留地形，可预览当前及未来 7 / 30 / 90 天的衰减情况；River 按区域展示交织的历史记录，支持画笔缩放和区域跟随；Pulse 是只读的回忆说明，展示排名、图谱提取、令牌预算和排除项。回忆视图会绘制带编号的路径，展示 AI 会获知的内容，并同时呈现确切的上下文。审阅矛盾、近似重复、正在淡去但重要的记忆以及可能的秘密；检测到秘密时，可使用 Redact。打开任意记忆即可检查或编辑；归档和记忆卡片中的矛盾操作都提供 6 秒内撤销。时间线按日期对记忆分组，洞察页包含数据和反思，设置页显示连接步骤和运行状况。欢迎页会引导你完成首次连接。

可使用浅色或深色模式（也可跟随系统设置），按 ⌘K / Ctrl+K 打开命令，并在不同记忆视图间切换时保持相同的项目范围。布局会适配手机，并支持键盘导航；地图旁还提供无障碍列表。

---

性能

指标	数值	方案
回忆延迟（100 条记忆）	~18ms p50	内存中的余弦扫描 + 重要性评分
存储吞吐量	~120 mem/s	SQLite WAL + 自动关联
嵌入	8ms/text	本地 ONNX/WASM（all-MiniLM-L6-v2）
冷启动（1k 条记忆）	~1.2s	完整数据库扫描 + 索引构建
缓存启动（1k 条记忆）	~45ms	持久化索引（快 27 倍）
每条记忆的存储空间	~1.3 KB	FP16 压缩（减少 2 倍）
仪表盘 JS 体积预算	初始加载 ≤ 200 KB / 按需加载的 Insights ≤ 125 KB / 按需加载的 3D 视图 ≤ 220 KB（gzip）	图表随 Insights 加载；three.js 随 Sky / Landscape 加载；check:bundle 强制执行限制

嵌入使用 ONNX Runtime WASM 在本地运行——不调用 OpenAI API、无费用，也不会有数据离开你的设备。

---

文档

文档	说明
docs/ARCHITECTURE.md	系统设计、数据流、组件概览
docs/API.md	完整的 REST API 参考（53 个端点）
docs/INTEGRATIONS.md	Claude Code、Ollama、REST、webhook、插件
docs/DEVELOPMENT.md	单体仓库、构建系统、参与贡献
docs/CONFIGURATION.md	环境变量、数据库、调优

交互式 Swagger UI：http://localhost:4901/docs

产品网站和交互式文档：engram.am

---

贡献

我们欢迎各种形式的贡献——修复错误、新增集成、为其他 AI 工具开发适配器、改进可视化效果以及完善文档。

请参阅 CONTRIBUTING.md 了解相关指南。

以下方面尤其欢迎大家提供帮助：

• 新增适配器 — LM Studio、llama.cpp、Anthropic API、OpenAI API
• 移动端 / 浏览器 — 轻量级浏览器端记忆客户端
• 多模态嵌入 — 在文本之外支持图像、音频
• 多设备云同步 — SQLite 仍作为本地引擎；各设备通过共享的 PostgreSQL 实例进行复制，使用 ENGRAM_SYNC_URL（参见 云同步）
• ANN 向量索引 — 用 HNSW 替代暴力余弦扫描，让召回不再随记忆数量线性扩展

---

使用示例

示例 1 — 会话开始：召回相关上下文

User: "Continue working on the auth refactor"
Claude: [calls recall_context("auth refactor current status")]
→ Returns past decisions, code patterns, and session notes about auth

工具：recall_context · 输入：{ "query": "auth refactor current status", "maxTokens": 1500 } · 输出：包含匹配记忆及其分数的格式化上下文块。

示例 2 — 存储一项决策

User: "Always use drizzle-kit migrate, never drizzle-kit push — it broke prod once"
Claude: [calls store_memory with type "procedural", importance 0.95]
→ Next session: search_memory("database migrations") surfaces this rule automatically

工具：store_memory → search_memory · 展示跨会话持久化。

示例 3 — 检测矛盾

User (day 1): "Production runs on PostgreSQL 15"
User (day 30): "We migrated prod to SQLite WAL last month"
Claude: [store_memory returns contradictions detected]
→ calls resolve_contradiction(strategy: "keep_newest")

工具：store_memory + resolve_contradiction · Engram 以 0.87 的置信度标记冲突，并归档过时的认知。

---

隐私政策

Engram 从设计上就以本地优先并保护隐私：

• 默认存储在本地。 所有记忆都存储在本地 SQLite 数据库中（~/.engram/engram.db）。除非你明确启用云同步，否则数据不会离开你的设备。
• 云同步需主动启用。 设置 ENGRAM_SYNC_URL 后，记忆会复制到由你拥有并控制的 PostgreSQL 数据库中——Engram 绝不会主动回传数据，也不会自行访问任何第三方服务。参见 云同步。
• 所有嵌入都在设备上运行。 all-MiniLM-L6-v2 模型通过 @xenova/transformers 在本地运行，不会调用外部嵌入 API。
• 不收集遥测数据。 Engram 不会收集使用统计信息、崩溃报告或任何分析数据。
• Webhook 需主动启用。 如果你配置了 webhook，记忆事件会发送到你指定的网址，完全由你掌控。

完整隐私政策：https://engram.am/privacy

---

许可证

MIT — 参见 LICENSE

---