AI导哈

AI代理持久化内存服务

为AI助手提供跨会话的长期记忆存储与检索功能，支持记忆的创建、更新、删除和智能召回。

  • by shetty4l
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 shetty4l/engram

使用说明

印迹

AI代理的持久内存。一个MCP服务器，为您的AI助手提供跨会话的长期记忆。

快速开始

选项1：从版本安装（推荐）

curl -fsSL https://github.com/shetty4l/engram/releases/latest/download/install.sh | bash

这将：

  • 下载并解压最新版本至 ~/srv/engram/<version>/
  • 安装依赖项并构建 engram CLI二进制文件
  • 将CLI符号链接到 ~/.local/bin/engram
  • 管理a latest 符号链接和删除旧版本（保留最后5个）
  • 打印MCP配置以添加到您的客户端

要求： bun, curl, tar, jq

添加到MCP客户端配置中：

{
  "engram": {
    "command": "bun",
    "args": ["run", "~/srv/engram/latest/src/index.ts"]
  }
}

方案2：地方发展

克隆仓库并运行安装脚本。如果您想贡献或修改印痕，请使用此选项。

git clone https://github.com/shetty4l/engram.git
cd engram
./scripts/setup-local.sh

选项3:AWS EC2（始终在线，跨设备）

只需一个命令即可部署到您的AWS帐户。需要配置AWS CLI。

git clone https://github.com/shetty4l/engram.git
cd engram
./scripts/deploy-aws.sh

这将：

  • 使用Amazon Linux 2023启动t3.small EC2实例
  • 自动安装Bun和Engram
  • 配置SSM以实现安全访问（无公共端口）
  • 输出MCP配置以添加到您的客户端

要求：

  • 已安装并配置AWS CLI(aws configure 或 aws sso login)
  • IAM权限：EC2、IAM、SSM

成本： 约15-20美元/月（t3.small+10GB EBS）。不使用时停止实例以节省成本。

清理：

./scripts/destroy-aws.sh

脚本创建 ~/.engram/ 包含您的密钥和实例信息。

OpenCode设置

在OpenCode中添加Engram作为MCP服务器。

先决条件

  • bun 安装
  • engram PATH上的CLI（由自动安装 install.sh，或运行 bun link 来自本地克隆）

将Engram MCP服务器添加到OpenCode

创建或更新 ~/.config/opencode/opencode.json:

bun run opencode:config

这将打印一个带有本地绝对路径的可粘贴配置块：

{
  "mcp": {
    "engram": {
      "type": "local",
      "enabled": true,
      "command": ["bun", "run", "/path/to/engram/src/index.ts"]
    }
  }
}

重新启动OpenCode以加载MCP服务器。

故障排除

  • engram: command not found：如果从发布版本开始安装，请确保 ~/.local/bin 在你的路径。如果从克隆运行，请运行 bun link 从回购。
  • 守护进程问题：
    • engram status
    • engram restart
    • curl http://127.0.0.1:7749/health

工具

remember

存储内存以供以后检索。

remember({ content: "User prefers TypeScript over JavaScript", category: "preference" })

参数：

  • content （必填）：内存内容
  • category （可选）： decision, pattern, fact, preference, insight
  • scope_id, chat_id, thread_id, task_id （可选）：隔离作用域过滤器
  • metadata （可选）：结构化元数据对象
  • idempotency_key （可选）：用于重试/更新的稳定身份密钥（推荐格式： <scope>:<category>:<topic-slug>)
  • upsert （可选）：首选 true 当存储器具有稳定的身份时；更新现有内存匹配 idempotency_key 而不是创建一个新的。需要 idempotency_key.

退货： { id: string, status: "created" | "updated" }

指导（简明）：

  • 更喜欢使用确定性密钥的持久内存（例如： <scope>:fact:validation-gate, <scope>:decision:storage-engine).
  • 对于没有稳定身份的一次性记忆，使用普通创建(upsert 省略或 false).

反常行为：

  • 当 upsert: true 以及具有相同功能的内存 idempotency_key （以及 scope_id)存在：覆盖 content, category, metadata，以及 embedding。不会改变 created_at, access_count, strength，或范围字段。
  • 使用完全替换语义：省略可选字段(category, metadata)设置为 null.
  • 当不存在匹配时：正常创建新内存。
  • 当 upsert 省略或 false：标准幂等性重播（返回缓存结果，无突变）。

recall

检索相关记忆。

recall({ query: "coding preferences", limit: 5 })

参数：

  • query （必填）：搜索什么
  • limit （可选）：最大结果（默认值：10）
  • category （可选）：按类别筛选
  • min_strength （可选）：最小强度阈值（0.0-1.0）
  • scope_id, chat_id, thread_id, task_id （可选）：作用域筛选器（功能标记）

forget

按ID删除存储的内存。

forget({ id: "memory-uuid" })

参数：

  • id （必填）：要删除的内存ID
  • scope_id （可选）：用于删除的范围保护（在以下情况下是必需的 ENGRAM_ENABLE_SCOPES=1)

退货：

  • id：请求的内存ID
  • deleted: true 如果存储器被删除， false 如果它不存在

capabilities

发现服务器版本和功能标志，以实现兼容性安全的客户端选择。

context_hydrate

检索辅助转弯的上下文记忆。行为镜像 recall，与 query 可选。

当用户要求用短语忘记时（例如“忘记API密钥的内存”）， 助理应该先打电话 recall 要确定候选人，请致电 forget 使用所选的内存ID。

记忆衰退

当不被访问时，记忆的强度会随着时间的推移而衰减，这有助于优先考虑相关知识：

  • 衰减率：每天0.95（14天后无法进入，强度约为50%）
  • 访问权限提升：访问内存会将其强度重置为1.0
  • 访问次数增加：频繁访问的内存可获得日志级奖励

CLI命令

# View decay status for all memories
engram decay

# Apply decayed strengths to database
engram decay --apply

# Preview what would be pruned (dry run)
engram prune --threshold=0.1 --dry-run

# Delete memories below threshold
engram prune --threshold=0.1

配置

用环境变量覆盖默认值：

ENGRAM_DECAY_RATE=0.95              # Daily decay multiplier (default: 0.95)
ENGRAM_ACCESS_BOOST_STRENGTH=1.0    # Strength after access (default: 1.0)

配置

数据库位置： ~/.local/share/engram/engram.db

用环境变量覆盖：

ENGRAM_DB_PATH=/custom/path/engram.db

功能标志（全部默认为禁用）：

ENGRAM_ENABLE_SCOPES=1
ENGRAM_ENABLE_IDEMPOTENCY=1
ENGRAM_ENABLE_CONTEXT_HYDRATION=1
ENGRAM_ENABLE_WORK_ITEMS=1

发展

贡献者规则

  • 在任何代码更改后，运行 bun run validate 在进入下一个任务之前。
  • 如果验证失败，请在打开或更新PR之前修复问题并重新运行验证。
# Core test suite (fast + CI-safe)
bun run test:core

# Full test suite (includes embedding/WASM tests)
bun run test:full

# Type check
bun run typecheck

# Lint
bun run lint

# All validation
bun run validate

# Full validation (includes embedding/WASM tests)
bun run validate:full

validate 有意运行核心套件(test:core)作为所需的CI门。 CI也运行 test:full 在每次推送和拉取请求中。如果全套断言通过 但Bun退出时会出现已知的变压器/WASM运行时崩溃(133)，CI记录警告 并继续。任何真正的测试失败仍然无法通过CI。

CI/CD

  • CI工作流程: .github/workflows/ci.yml
    • 对每个推送和拉取请求运行
    • 需要执行 bun run validate
    • 执行 bun run test:full 对已知的Bun出口进行特殊处理 133
  • 发布工作流程: .github/workflows/release.yml
    • CI成功时自动触发 main
    • 从最新的git标签自动递增补丁版本
    • 创建源代码tarball并发布GitHub Release install.sh
    • 安装： curl -fsSL https://github.com/shetty4l/engram/releases/latest/download/install.sh | bash

路线图

  • 切片1 ✅: 具有强度/新近度排序的基本CRUD
  • 切片2 ✅: 使用FTS5进行全文搜索
  • 切片3 ✅: HTTP服务器和守护进程
  • 切片4 ✅: 基于局部嵌入的语义搜索
  • 切片5 ✅: 内存衰减算法
  • 切片6：重复数据删除和冲突检测
  • 切片7：出口/进口，便于携带

许可证

麻省理工学院

相关 MCP