Engram Rs

engram-rs

AI エージェント向けのメモリエンジンです。2 つの軸を持ちます。時間（3 層の減衰と昇格）と空間（自己組織化するトピックツリー）です。重要なメモリは昇格し、ノイズは薄れ、関連する知識は自動的にクラスタ化されます。

ほとんどのエージェントメモリはフラットなストアです。すべてを放り込み、キーワード検索で取り出すだけです。忘却もなく、整理もなく、ライフサイクルもありません。engram-rs は、メモリを本当に役立つものにする部分、つまり重要でないものを忘れ、重要なものを浮かび上がらせる能力を追加します。

単一の Rust バイナリ、1 つの SQLite ファイル、外部依存ゼロです。Python も Redis もベクトル DB も不要で、curl | bash で動作します。バイナリは約 10 MB、RSS は約 100 MB、検索レイテンシは 1 桁ミリ秒です。

クイックスタート

# 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

できること

3 層ライフサイクル

Atkinson–Shiffrin 記憶モデルに着想を得て、メモリは重要度に応じて 3 つの層にまたがって管理されます。

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

• Buffer: すべての新しいメモリの入口です。一時的なステージングであり、しきい値を下回ると削除されます
• Working: 統合によって昇格します。決して削除されず、重要度は種類ごとに異なる速度で減衰します
• Core: 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 エポック	ワークフロー、指示、ハウツー

アルゴリズムの可視化

グラフ	示す内容
	シグモイドスコア圧縮。 生のスコアはシグモイド関数を通してマッピングされ、1.0 に漸近します。関連性の高い結果は同じ値に押しつぶされることなく、区別可能なまま保たれます。
	エビングハウスの忘却曲線。 種類ごとに異なる速度で指数関数的に減衰します。エピソード記憶が最も速く薄れ、手続き記憶が最も遅くなります。下限が 0.01 であるため、記憶が完全に消えることはなく、 precise なクエリの下では検索可能なまま残ります。
	種類 × レイヤーの重みバイアス。 加算的なバイアスが記憶の重みを種類とレイヤーに応じて調整します。手続き+コアの記憶が最も上位にランクされ、エピソード+バッファーが最も下位になりますが、その広がりは範囲内に収まるため、単一の組み合わせが支配することはありません。
	強化シグナル。 反復とアクセスのボーナスは対数的な飽和に従います。初期のやり取りが最も重要で、後のものは収穫逓減しか寄与しません。これにより「たまに使われる」と「毎日使われる」を区別します。
	使うか失うか。 左：決して思い出されない記憶はバッファーレイヤーへと減衰します。右：定期的な想起が活性化ブーストを引き起こし、その記憶をワーキングレイヤーにとどめます。破線は比較用に、想起されなかった場合の軌跡を示しています。

セマンティックな重複排除とマージ

同じ内容を異なる言葉で表現している 2 つの記憶は、自動的に検出されマージされます。

"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

セクション	内容	目的
コア	永続的なルールとアイデンティティの全文	忘れられないもの
最近	最近変更された記憶	短期的な継続性
トピック	トピックインデックス（目次）	必要に応じて掘り下げ、全体を読み込まない
トリガー	アクション前のタグ	危険な操作の前に教訓を自動想起

エージェントはディレクトリを読み、関連するトピックを見つけ、必要に応じて POST /topic を呼び出して展開します。

検索と取得

セマンティック埋め込み + CJK トークン化対応の BM25 キーワード検索（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. トリアージ — 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

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-...

2 層のモデル設定 — 判断には強力なモデル、テキスト処理には軽量なモデル：

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 ダッシュボード

http://localhost:3917/ui に組み込みの Web UI があり、メモリの閲覧、トピックツリーの表示、LLM 使用状況の監視ができます。

仕様

バイナリ	約 10 MB
メモリ	本番環境で約 100 MB RSS
ストレージ	SQLite、外部データベース不要
言語	Rust
プラットフォーム	Linux、macOS、Windows（x86_64 + aarch64）
ライセンス	MIT

ライセンス

MIT