Holographic Memory

Holographic Memory

エージェントやアプリ向けのローカルメモリです。全文検索とベクトル検索、メモリ API、ベクトル記号型のファクトストアを、ネットワーク通信を行わない、組み込み可能な 1 つの Rust エンジンにまとめています。

ウェブサイト · ドキュメント · はじめに · 結果 · 「ホログラフィック」と呼ばれる理由 · 機能 · 制限事項 · 貢献

Holographic Memory（略して HMS）は、テキスト、ベクトル、事実をマシン上のディレクトリに保存し、再び検索するための Rust ライブラリです。Node.js バインディング、C、WASM、UniFFI バインディング、Python クライアントを備えた HTTP サーバー、MCP サーバーが付属しています。機能を有効にして要求しない限り、サービスへの呼び出し、テレメトリー、モデルのダウンロードは発生しません。

対象ユーザー

主な結果

各行から、その結果の元となったコミット済みファイルに移動できます。ここに示すのは単一マシンで、記載のプロトコルに基づく結果であり、ご自身のデータでのテストに代わるものではありません。

劣っている点

手法、区間、すべての劣後結果については、docs/benchmarks および ベンチマークページをご覧ください。 hms-bench table により benchmarks/results/competitive/ から生成。手法と注意事項については docs/benchmarks/COMPARISON.md を参照してください。W = HMS が優位（95%区間が同等を含まない）、T = 同等、L = 比較対象が優位。

はじめに

一度クローンします：git clone https://github.com/writerslogic/holographic-memory && cd holographic-memory。 オフラインのエージェントメモリのデモを実行します：cargo run --release --example demo-offline-agent。

cargo add holographic-memory --git https://github.com/writerslogic/holographic-memory

use holographic_memory::{DocumentInput, HmsCore, SearchOptions};

let dir = tempfile::tempdir()?;
let hms = HmsCore::new(4096, Some(dir.path().display().to_string()), None)?;
hms.memorize_document(DocumentInput {
    id: "backups".into(),
    text: "Restore deleted documents from verified backups.".into(),
    source_uri: Some("operations.md".into()),
    version: Some("1".into()),
    metadata: Some(serde_json::json!({ "project": "alpha" })),
    chunk_words: None, overlap_words: None, store_text: None, embeddings: None, title_weight: None,
})?;
let hits = hms.search_documents("restore backups", &SearchOptions::default())?;
println!("{} {:?}", hits[0].document_id, hits[0].source_uri);

npm install holographic-memory

npm ci --omit=optional && npm run build

const { HolographicMemorySystem } = require('holographic-memory')
const { DocumentMemory } = require('holographic-memory/semantic')

async function main() {
  const dir = require('node:fs').mkdtempSync(require('node:path').join(require('node:os').tmpdir(), 'hms-readme-'))
  const memory = new DocumentMemory(new HolographicMemorySystem(4096, dir))
  await memory.memorize({
    id: 'backups', text: 'Restore deleted documents from verified backups.',
    sourceUri: 'operations.md', version: '1', metadata: { project: 'alpha' },
  })
  const [hit] = await memory.search('restore backups', { filter: { project: 'alpha' } })
  console.log(hit.documentId, hit.sourceUri, hit.text)
  await memory.flush()
}
main().catch(error => { console.error(error); process.exit(1) })

cargo build --release --features server --bin hms-server
HMS_API_KEY=change-me target/release/hms-server --input-dim 384 &
uv pip install holographic-memory-sdk

from holographic_sdk import HolographicClient

client = HolographicClient(url="http://127.0.0.1:8080", api_key="change-me", tenant_id="demo")
client.add_documents([{"id": "a", "vector": [0.1] * 384, "text": "hello", "metadata": {}}])
print(client.query([0.1] * 384, top_k=1)["matches"][0]["id"])

npx -y holographic-memory-mcp                                # stdio; downloads a verified binary on first run
npx -y holographic-memory-mcp --transport http               # http://127.0.0.1:8765/mcp

cargo build --release --features mcp,security --bin hms-mcp   # add local-models for semantic recall
./target/release/hms-mcp                                       # stdio
./target/release/hms-mcp --transport http                      # http://127.0.0.1:8765/mcp

5 分でできるクイックスタート では、Rust、Python、Node での取り込み、検索、SQLite FTS5 との比較、暗号化について説明しています。また、CI ではすべてのプルリクエストでそのコードを実行します。埋め込みもネットワークも使わずにエージェントメモリ全体を実行するには、cargo run --example demo-offline-agentを実行してください。

なぜ「ホログラフィック」と呼ばれるのですか？

ホログラムでは、プレートのどの断片にも、全体像をぼんやりと写したものが含まれています。半分に切っても、半分の画像ではなく、解像度が下がった全体像が得られます。ホログラフィック縮約表現とベクトル記号アーキテクチャ（VSA）は、メモリにこの性質をもたらします：

• バインドでは、2 つのベクトル（ここでは疎なビット集合の XOR）を結び付け、役割と値を対応させます：capital ⊗ paris。 役割を使ってもう一度バインドすると、値のノイズを含むコピーを復元できます。
• バンドルでは、複数のバインド済みペアを固定サイズの 1 つのベクトルにまとめます。結果は各要素と類似したままなので、1 つのベクトルにレコード全体を格納でき、1 つのビットが特定の事実を保持することはありません。
• 共鳴による想起。 ノイズを含む手掛かりを与えると、保存されたパターンのうち最も近いものが選ばれます（類似性検索、Hopfield によるクリーンアップ）。ベクトルが損傷すると、いくつかの項目が削除されるのではなく、すべての項目が少しずつ劣化するため、ノイズが増えても想起は徐々に低下します。

数行のコードで動作を確認できます（100 個の項目を和集合バンドルにまとめ、段階的に損傷させます）： cargo run --release --manifest-path examples/quickstart/rust/Cargo.toml --bin holographic。

**ここで文字どおりホログラフィックなのは、**疎なハイパーベクトル型と、そのバインド、バンドル、置換の各操作です。また、関係型の「意味メモリ」（トリプルをバインド済みの複合表現として保存し、複数ホップクエリと Hopfield によるクリーンアップを行います）、和集合バンドルのメンバーシップテスト、共鳴ネットワークも該当します（いずれも experimental 機能の背後にあります）。

**従来型のエンジニアリングにあたるのは、**ドキュメント検索（ステミング済み BM25 と厳密なコサイン類似度の組み合わせで、ハイパーベクトルは読み取りません）、グラフおよび転置ファイルのベクトルインデックス、メモリ API、ジャーナル型ストレージ、サーバーです。これらについては、ホログラフィックな動作をうたっていません。テスト済みの数値を含む詳しい説明は、 概念を参照してください。

現在提供されている機能

上記の機能のうち、文書検索とベクトルインデックスを除くすべては、デフォルトで無効になっているCargo featureまたはランタイムオプションで利用します。Cargo featuresに一覧があります。

アーキテクチャ

flowchart TB
  subgraph bindings["Bindings and servers"]
    rust["Rust crate"]
    node["Node.js (napi)"]
    ffi["C, WASM, UniFFI"]
    python["Python: holographic-memory-sdk"]
    server["hms-server (HTTP)"]
    mcp["hms-mcp (stdio, HTTP)"]
  end
  subgraph engine["Engine API"]
    core["HmsCore: documents, vectors, facts, mutation gate"]
    prov["Security and provenance: signed audit log, COSE/SCITT"]
  end
  subgraph indexes["Indexes and memory"]
    text["Text index: blocked postings, BM25, Boolean and phrase"]
    vector["Vector index (qgraph): vertex file, updatable delta, query-aware projection"]
    memory["Memory API: remember, recall, forget, conversation memory"]
    vsa["Vector-symbolic layer: bind, bundle, Hopfield cleanup"]
  end
  subgraph storage["Storage"]
    journal["Journal and checkpoints"]
    segments["Append-only segments (CRC32, LZ4)"]
    mapped["Memory-mapped files"]
    crypto["AES-256-GCM encryption (optional)"]
  end
  python --> server
  rust --> core
  node --> core
  ffi --> core
  server --> core
  mcp --> core
  core --> text
  core --> vector
  core --> memory
  core --> vsa
  core --> prov
  memory --> text
  text --> journal
  vector --> journal
  memory --> journal
  journal --> segments
  segments --> mapped
  segments --> crypto

モジュールマップ：docs/ARCHITECTURE.md。

制限事項

• 匿名ではありません。 ハイパーベクトルのスケッチと用語カウントは暗号化ではないため、ストアを持つ人なら誰でも候補テキストをエンコードして比較できます。storeText: false にしても用語カウント、ID、埋め込みは保持されるため、プライバシー保護にはなりません。
• ドキュメント検索は従来型です。 ハイパーベクトルは使用せず、ホログラフィックな部分は代数と意味記憶です。
• 1つのストアにつき書き込みプロセスは1つです。 2つ目の書き込みプロセスは、ロックエラーによりオープン時に失敗します。
• 容量の数値は保証ではなく目安であり、テスト済みの範囲についてのみ示しています（容量）。
• ベンチマーク結果は単一のマシンでのものです。 条件は各結果ファイルに記載されています。シングルコアの ann-benchmarks の実行結果と VIBE の高再現率の測定点は性能低下を示しています（不得意な点を参照）。
• マスキングは難読化です。 クライアント側のベクトルマスキングでは、すべてのペア間の類似度が保持されます。
• ストアはディレクトリであり、HmsCore::new(.., None, ..) は現在のディレクトリを使用します。

詳細な声明はdocs/PRIVACY.mdをご覧ください。脆弱性はSECURITY.mdを通じて非公開で報告してください。

貢献

CONTRIBUTING.mdには、セットアップ、CIで実行されるチェック、DCOのサインオフ（git commit -s、CLAは不要）について記載されています。初めての方向けの課題またはディスカッションから始めてください。行動規範をご覧ください。ベンチマークを変更した場合は、変更箇所に該当する結果ファイルを再生成してください。READMEでは、記憶に頼った数値ではなくファイルを参照しています。

ライセンス

Apache-2.0。LICENSEをご覧ください。コピーレフト義務なしで、ネットワークサービスを含むオープンソースまたはプロプライエタリソフトウェアで使用、変更、組み込みができます。crate 0.6.1までのリリースは AGPL-3.0-or-later のもとで公開されており、引き続きその条件で利用できます。