Engram Rs

engram-rs

面向 AI Agent 的记忆引擎。两个维度：时间（三层衰减与晋升）和空间（自组织主题树）。重要记忆会晋升，噪声会淡去，相关知识会自动聚类。

大多数 Agent 的记忆都是扁平存储——把所有内容一股脑存进去，再通过关键词搜索取回。没有遗忘、没有组织、没有生命周期。engram-rs 补上了让记忆真正有用的部分：忘记无关内容，并呈现重要内容的能力。

单个 Rust 二进制文件，一个 SQLite 文件，零外部依赖。不需要 Python、Redis 或向量数据库——执行 curl | bash 即可运行。二进制文件约 10 MB，RSS 约 100 MB，搜索延迟仅为个位数毫秒。

快速开始

# 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

功能介绍

三层生命周期

受 Atkinson–Shiffrin 记忆模型启发，记忆会根据重要性在三个层级中进行管理：

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

• 缓冲层：所有新记忆的入口。临时暂存——低于阈值时会被淘汰
• 工作层：通过整合晋升。永不删除，不同类型的记忆按不同速率衰减重要性
• 核心层：通过 LLM 质量门槛晋升。永不删除

LLM 质量门槛

晋升不是基于规则的猜测——LLM 会结合上下文评估每条记忆，并决定它是否确实值得长期保留。

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

自动衰减

衰减由活动驱动——仅在主动整合周期中触发，而非依据墙上时钟时间。如果系统处于空闲状态，记忆会保持完整。

指数衰减遵循艾宾浩斯遗忘曲线——初期衰减快，随后逐渐放缓，形成长尾。记忆永远不会完全消失（下限 = 0.01），在精确查询下仍可检索。回忆起某条记忆时，会获得激活加成，从而强化频繁使用的知识。

类型	衰减率	半衰期	使用场景
episodic	最快	约 35 个周期	事件、经历、有时间限制的上下文
semantic	中等	约 58 个周期	知识、偏好、经验（默认）
procedural	最慢	约 173 个周期	工作流、指令、操作指南

算法可视化

图表	展示内容
	Sigmoid 分数压缩。 原始分数通过 sigmoid 函数映射，并渐近趋近于 1.0。高相关性结果仍可区分，不会被压缩成相同的值。
	艾宾浩斯遗忘曲线。 指数衰减速率因类型而异——情景记忆衰减最快，程序性记忆最慢。衰减下限为 0.01，这意味着记忆不会完全消失；通过精确查询仍可检索到。
	类型 × 层级权重偏置。 加性偏置会根据类型和层级调整记忆权重。程序性 + 核心记忆排名最高，情景 + 缓冲区记忆最低——但权重差距始终有限，因此没有任何单一组合会占据主导地位。
	强化信号。 重复次数和访问奖励遵循对数饱和规律。早期交互最重要；后续交互的收益递减，从而区分「偶尔使用」和「每天使用」。
	用进废退。 左图：从未被回忆的记忆会衰减至缓冲区层。右图：周期性回忆会触发激活加成，使记忆留在工作层。虚线显示未被回忆的变化轨迹，供对比。

语义去重与合并

两条记忆表达相同的内容，只是措辞不同？系统会自动检测并合并：

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

自组织主题树

向量聚类会将相关记忆分组，大模型为聚类命名。无需手动标记：

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

它解决的问题是：向量搜索要求提出正确的问题。主题树让 Agent 可以按主题浏览——扫描目录，深入查看合适的分支。

触发器

为记忆添加 trigger:deploy，Agent 就能在执行部署前回忆所有相关经验：

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

会话恢复

Agent 唤醒后调用 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 按需展开。

搜索与检索

语义嵌入 + BM25 关键词搜索，并使用 CJK 分词（jieba）。基于 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. 分流 — 大模型对新的缓冲区记忆进行分类
4. 筛选 — 大模型批量评估晋升候选项
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

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

大模型配置

engram-rs 无需大模型也能运行——关键词搜索和基于规则的生命周期管理仍然有效。添加大模型即可启用智能功能（分流、筛选、合并、主题命名）：

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 Agent

添加到 Agent 的系统提示词中：

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 使用情况。

规格

二进制文件	约 10 MB
内存	生产环境中约 100 MB RSS
存储	SQLite，无需外部数据库
语言	Rust
平台	Linux、macOS、Windows（x86_64 + aarch64）
许可证	MIT

许可证

MIT