Holographic Memory

Holographic Memory

为 Agent 和应用提供本地记忆：全文和向量搜索、记忆 API，以及向量符号事实存储，全部集成于一个可嵌入的 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。 运行离线 Agent 记忆演示：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

五分钟快速入门 将介绍 Rust、Python 和 Node 中的数据摄取、搜索、与 SQLite FTS5 的比较以及加密；CI 还会在每个拉取请求中运行这些代码。若要体验无需嵌入和网络的完整 Agent 记忆，请运行 cargo run --example demo-offline-agent。

为什么叫“全息”？

在全息图中，底片的每个碎片都包含整幅图像的模糊副本。将它切成两半，你得到的仍是整幅图像，只是分辨率较低，而不是半幅图像。全息降维表示和向量符号架构（VSA）让记忆具备了这一特性：

• 绑定两个向量（此处为稀疏位集合的异或），将角色与填充值关联起来：capital ⊗ paris。再次用角色进行绑定，即可还原出填充值的噪声副本。
• 将多个绑定对捆绑到一个固定大小的向量中。结果与每个组成部分仍保持相似，因此一个向量就能存储完整记录，且没有任何单个位承载某条事实。
• **通过共振回忆。**输入带噪提示，最近的已存储模式就会胜出（相似度搜索、Hopfield 清理）。损坏向量会让每个条目都略微退化，而非删除少数条目，因此噪声越大，回忆能力就逐渐下降。

你可以用几行代码观察这一过程（将 100 个条目合并为并集，并逐步损坏）： cargo run --release --manifest-path examples/quickstart/rust/Cargo.toml --bin holographic。

**这里哪些内容是真正的全息技术：**稀疏超向量类型及其绑定、捆绑和置换操作；关系型“意义记忆”（将三元组存储为绑定复合体，支持多跳查询和 Hopfield 清理）；并集捆绑成员资格测试和共振器网络（均需启用 experimental 功能）。

**哪些内容属于常规工程：**文档搜索（词干化 BM25 加精确余弦相似度；不读取超向量）、图索引和倒排文件向量索引、记忆 API、日志存储和各类服务端。这些内容均不声称具备全息行为。包含测试数据的详细版本见 概念。

当前提供的功能

除文档搜索和向量索引外，上述所有功能都需要通过默认关闭的 Cargo 功能或运行时选项启用；Cargo 功能列出了所有选项。

架构

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 和嵌入，因此不是隐私保护措施。
• 文档搜索采用传统方式。 它不使用超向量；全息部分是代数和语义记忆。
• 每个存储库只能有一个写入者。 第二个写入进程在打开时会因锁定错误而失败。
• 容量数据是点值，并非保证值，且仅针对已测试范围给出（容量）。
• 基准测试结果来自单台机器。 条件见各结果文件；单核 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 发布，并继续适用这些条款。