LocalEngram

LocalEngram 是面向 AI Agent 的本地向量记忆服务。它通过 MCP 提供记忆写入、混合检索、更新、遗忘、列表、压缩和统计工具；运行期间不调用在线 API，数据默认保存在用户主目录下的 .local-engram/data。

需要交给 AI Agent 自动安装时，请直接提供 INSTALL.md。标准入口是 node scripts/install.mjs。

技术栈

| 层级 | 实现 | |---|---| | 运行时 | Node.js 24+ | | 语言 | TypeScript 5.9，严格模式 | | MCP | 官方 @modelcontextprotocol/sdk，默认 stdio | | 数据库 | Node 内置 node:sqlite，SQLite + WAL | | 关键词检索 | SQLite FTS5 | | 向量存储 | SQLite BLOB 中的 Float32 向量 | | 向量检索 | 纯 TypeScript 余弦相似度 | | 混合排序 | 向量召回 + FTS5 + RRF | | CLI | Commander | | 测试 | Node 原生 test runner |

这套实现没有 Python 环境、虚拟环境、原生 npm 数据库插件或独立数据库服务。Node 24 自带 SQLite，减少了 Windows 上的编译和版本冲突。

当前能力

• stdio MCP 服务，不监听网络端口
• namespace、agentId、userId、kind 多层数据隔离
• 内容去重、重要性、访问计数、过期时间
• 单条与最多 100 条批量写入，逐项报告结果且不因单条失败丢失其他成功项
• 软删除、恢复、永久删除和数据库压缩
• 可迁移 JSON 快照、SQLite 在线备份与健康诊断
• 默认纯本地 384 维哈希向量，无需模型即可工作
• 数据库记录嵌入模型与维度，防止不同向量混用
• 命令行覆盖全部主要记忆操作

默认哈希向量适合工作流验证和词法相关检索，不等同于语义模型。后续可在 EmbeddingProvider 接口下加入 ONNX Runtime，本地加载 multilingual-e5-small 等模型，不需要改 MCP、服务或存储层。

安装

需要 Node.js 24 或更高版本：

发布到 npm 后可以直接运行，无需全局安装：

npx -y local-engram doctor
npx -y local-engram serve

从源码开发或安装时：

npm install
npm run build
npm test

也可以执行完整自动安装：

node scripts/install.mjs

首次安装 npm 依赖可能需要访问软件源；完成安装和构建后，LocalEngram 的正常运行不需要联网。

命令行

# 创建数据库
npx -y local-engram init

# 写入并搜索
npx -y local-engram store "用户偏好使用 VS Code" --kind preference
npx -y local-engram search "用户喜欢什么编辑器？"

# 查看与维护
npx -y local-engram list
npx -y local-engram stats
npx -y local-engram doctor
npx -y local-engram backup
npx -y local-engram compact

# 启动 MCP stdio 服务
npm start

node:sqlite 在当前 Node 24 版本仍会输出实验性 API 提示，因此脚本中只关闭了这一类提示；这不影响 SQLite 数据格式或功能。

配置

默认数据库位于用户主目录的 .local-engram/data/local-engram.db。首次运行会自动创建目录和数据库，不需要执行额外的初始化步骤。

可以通过 --data-dir 临时覆盖数据目录，也可以复制 local-engram.example.json 为项目级 local-engram.json，实际配置文件已被 Git 忽略：

{
  "dataDir": "./data",
  "databaseName": "local-engram.db",
  "embeddingProvider": "hash",
  "embeddingModelId": "local-engram-hash-v1",
  "embeddingDimension": 384
}

也可以使用环境变量：

LOCAL_ENGRAM_DATA_DIR
LOCAL_ENGRAM_DATABASE_NAME
LOCAL_ENGRAM_EMBEDDING_MODEL_ID
LOCAL_ENGRAM_EMBEDDING_DIMENSION

配置优先级为：CLI 参数、环境变量、当前工作目录中的 local-engram.json、用户目录默认值。

MCP 客户端配置

推荐通过 npm 包启动，无需配置 Node 或项目的绝对路径：

{
  "mcpServers": {
    "local-engram": {
      "command": "npx",
      "args": [
        "-y",
        "local-engram",
        "serve"
      ]
    }
  }
}

Windows 客户端如果不能直接解析 npx，可将 command 改为 npx.cmd。需要固定数据位置时，在 args 末尾追加 "--data-dir", "<绝对路径>"。

服务提供以下 MCP 工具：

memory_store
memory_store_batch
memory_search
memory_get
memory_update
memory_forget
memory_restore
memory_list
memory_compact
memory_stats
memory_health

建议每次写入一条原子记忆，例如“用户偏好使用 VS Code”，不要把整段对话直接保存为一条记忆。不同 Agent 或用户应始终传入稳定的 namespace、agentId 和 userId。

开发命令

npm run check
npm run build
npm test

发布

GitHub Actions 会在 main 分支和 Pull Request 上执行类型检查、完整测试与 npm 打包预检。发布前需在 GitHub 仓库的 Actions secrets 中配置 NPM_TOKEN，然后让 package.json 版本与标签保持一致并推送标签：

npm version patch
git push origin main --follow-tags

v* 标签会触发 npm 公开发布，并将同一份 .tgz 包上传到对应的 GitHub Release。重复发布相同版本会被 npm 拒绝。

数据安全与规模

• MCP 默认只使用 stdio，不开放 HTTP 端口。
• data/、models/ 和实际配置文件不会提交到 Git。
• memory_forget 默认软删除；memory_compact 会永久清理软删除及过期记录。
• 数据库本身未加密；敏感设备应配合系统磁盘加密和目录权限。
• 当前余弦检索在进程内扫描当前作用域，适合个人 Agent 的首版数据量。达到数十万条向量后，可在存储接口下接入 sqlite-vec 或 Qdrant。