Engram Rs

英格拉姆

   ](https://github.com/kael-bit/engram-rs) ](https://ghcr.io/kael-bit/engram-rs)

AI代理的内存引擎。两轴： 时间 （三层衰减和提升）和 空间 （自组织主题树）。重要记忆得到提升，噪音消失，相关知识自动聚类。

大多数代理内存都是一个平面存储——转储所有内容，通过关键字搜索将其取回。没有遗忘，没有组织，没有生命周期。engram-rs增加了使记忆真正有用的部分：忘记无关紧要的事情并浮出水面的能力。

单个Rust二进制文件，一个SQLite文件，零外部依赖。没有Python，没有Redis，没有矢量数据库-- curl | bash 然后它就跑了。~10 MB二进制文件，~100 MB RSS，单位毫秒搜索延迟。

快速开始

# Install (interactive — will prompt for embedding provider config)
curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash

# Store a memory
curl -X POST http://localhost:3917/memories \
  -d '{"content": "Always run tests before deploying", "tags": ["deploy"]}'

# Recall by meaning
curl -X POST http://localhost:3917/recall \
  -d '{"query": "deployment checklist"}'

# Restore full context (session start)
curl http://localhost:3917/resume

它的作用

三层生命周期

灵感来自 阿特金森-希夫林记忆模型，记忆按重要性分为三层进行管理：

Buffer (short-term) → Working (active knowledge) → Core (long-term identity)
      ↓                       ↓                           ↑
   eviction              importance decay           LLM quality gate

• 缓冲：所有新记忆的入口。临时搭建——低于阈值时被驱逐
• 工作：通过整合得到提升。从未删除，重要性按种类以不同的速度衰减
• 核心：通过法学硕士质量门晋升。从未删除

LLM质量门

晋升不是基于规则的猜测——LLM在上下文中评估每个记忆，并决定它是否真正值得长期保留。

Buffer → [LLM gate: "Is this a decision, lesson, or preference?"] → Working
Working → [sustained access + LLM gate] → Core

自动衰减

衰退是由活动驱动的——它只在活跃的整合周期内发生，而不是挂钟时间。如果系统处于空闲状态，记忆将保持不变。

指数衰减 遵循 艾宾浩斯遗忘曲线 --先是快，然后是长尾。记忆永远不会完全消失（floor=0.01），在精确查询下仍然可以检索。当回忆起一段记忆时，它会得到 激活增强加强常用知识。

算法可视化

语义推导与合并

两个记忆用不同的词说同一件事？自动检测并合并：

"use PostgreSQL for auth" + "auth service runs on Postgres"
→ Merged into one, preserving context from both

自组织主题树

向量聚类将相关的内存组合在一起，LLM为这些集群命名。无需手动标记：

Memory Architecture
├── Three-layer lifecycle [4]
├── Embedding pipeline [3]
└── Consolidation logic [5]
Deploy & Ops
├── CI/CD procedures [3]
└── Production incidents [2]
User Preferences [6]

这解决了一个问题：向量搜索需要问正确的问题。主题树让代理 主题浏览 --扫描目录，深入到正确的分支。

触发器

用标签标记记忆 trigger:deploy，并且代理可以在执行之前回忆所有部署经验教训：

curl -X POST http://localhost:3917/memories \
  -d '{"content": "LESSON: always backup DB before migration", "tags": ["trigger:deploy", "lesson"]}'

# Pre-deployment check
curl http://localhost:3917/triggers/deploy

会话恢复

特工醒来，打电话 GET /resume，获取完整的上下文。无需文件扫描：

=== Core (24) ===
deploy: test → build → stop → start (procedural)
LESSON: never force-push to main
...

=== Recent ===
switched auth to OAuth2
published API docs

=== Topics (Core: 24, Working: 57, Buffer: 7) ===
kb1: "Deploy Procedures" [5]
kb2: "Auth Architecture" [3]
kb3: "Memory Design" [8]
...

Triggers: deploy, git-push, database-migration

Agent读取目录，查找相关主题，调用 POST /topic 根据需求进行扩张。

搜索与检索

语义嵌入+基于CJK标记的BM25关键字搜索(结巴).IDF加权得分——罕见术语被提升，常见术语自动降低权重。没有要维护的停用词列表。

# Semantic search
curl -X POST http://localhost:3917/recall \
  -d '{"query": "how do we handle auth", "budget_tokens": 2000}'
# Note: min_score defaults to 0.30. Use "min_score": 0.0 to get all results.

# Topic drill-down
curl -X POST http://localhost:3917/topic \
  -d '{"ids": ["kb3"]}'

后台维护

全自动、活动驱动——无写入意味着跳过循环：

合并（每30分钟一次）

1. 衰变 --降低未表达记忆的重要性
2. 去重 --合并几乎相同的记忆（余弦>0.78）
3. 分诊 --LLM对新的缓冲存储器进行分类
4. 门 --LLM批量评估晋升候选人
5. 调和 --解析不明确的相似对（结果缓存）
6. 主题树重建 --重新群集和命名

主题提取 --当一个主题变得太大（10+个记忆）时，重叠的内容会被压缩成更少、更丰富的条目。

命名空间隔离

单个实例，多个项目。使用 X-Namespace 隔离：

curl -X POST http://localhost:3917/memories \
  -H "X-Namespace: my-project" \
  -d '{"content": "API uses OAuth2 bearer tokens"}'

安装

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/kael-bit/engram-rs/main/install.ps1 | iex

码头工人

docker run -d --name engram-rs \
  -p 3917:3917 \
  -v engram-data:/data \
  -e ENGRAM_LLM_URL=https://api.openai.com/v1 \
  -e ENGRAM_LLM_KEY=sk-... \
  ghcr.io/kael-bit/engram-rs:latest

LLM配置

engram rs在没有LLM的情况下工作——关键字搜索和基于规则的生命周期仍然有效。添加LLM可以解锁智能功能（分流、门、合并、主题命名）：

export ENGRAM_LLM_URL=https://api.openai.com/v1
export ENGRAM_LLM_KEY=sk-...

# Any OpenAI-compatible API (Ollama, LM Studio, etc.)
export ENGRAM_LLM_URL=http://localhost:11434/v1

# Anthropic native
export ENGRAM_LLM_PROVIDER=anthropic
export ENGRAM_LLM_KEY=sk-ant-...

两层模型配置——用于判断的强模型，用于文本处理的轻量级模型：

ENGRAM_GATE_MODEL=gpt-4o          # quality decisions
ENGRAM_LLM_MODEL=gpt-4o-mini     # text processing

对于AI代理

在代理的系统提示中添加：

Set up engram-rs (persistent memory) by following the guide at:
https://raw.githubusercontent.com/kael-bit/engram-rs/main/docs/SETUP.md

整合

适用于Claude Code、Cursor、Windsurf、OpenClaw和任何兼容MCP的工具。

17个MCP工具(MCP文件)|完整的HTTP API(安装指南)

# MCP (Claude Code)
npx engram-rs-mcp

# MCP (Cursor / Windsurf / generic)
{"mcpServers": {"engram": {"command": "npx", "args": ["-y", "engram-rs-mcp"]}}}

Web仪表板

内置web UI http://localhost:3917/ui 用于浏览记忆、查看主题树和监视LLM使用情况。

规格

许可证

麻省理工学院