Holographic Memory

Holographic Memory

Local memory for agents and apps: full-text and vector search, a memory API and a vector-symbolic fact store in one embeddable Rust engine that makes no network calls.

Website · Docs · Get started · Results · Why "holographic"? · Capabilities · Limits · Contribute

What it is

Holographic Memory (HMS for short) is a Rust library that stores text, vectors and facts in a directory on your machine and finds them again. It ships with Node.js bindings, C, WASM and UniFFI bindings, an HTTP server with a Python client, and an MCP server. There are no service calls, no telemetry and no model downloads unless you turn on a feature that asks for one.

Who it's for

Headline results

Every row links to the committed file it comes from. These are single machines and stated protocols, not a substitute for testing your own data.

Where it's behind

Method, intervals and every loss: docs/benchmarks and the benchmarks pages.

Generated from benchmarks/results/competitive/ by hms-bench table; method and caveats in docs/benchmarks/COMPARISON.md. W = HMS ahead (95% interval excludes parity), T = tie, L = a comparator is ahead.

Get started

Clone once: git clone https://github.com/writerslogic/holographic-memory && cd holographic-memory. Run the offline agent-memory demo with cargo run --release --example demo-offline-agent.

Rust

From your own Rust project, add the current Apache-2.0 source:

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

The published crate 0.6.1 remains AGPL-3.0-or-later.

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);

Node.js

The npm registry carries only the deprecated 0.3.0; build the native module from source (Rust required):

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

const { HolographicMemorySystem } = require('./index.js')
const { DocumentMemory } = require('./semantic.js')

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) })

Server and Python

The Python package holographic-memory-sdk is an HTTP client for hms-server, which stores vectors you supply. (holographic-memory-py provides native vector search and phase vectors, but no document search.)

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"])

Endpoints, flags, tenants and limits are in the server docs. A runnable Python quickstart with a toy embedder is in examples/quickstart/python.

MCP

hms-mcp serves a store to any Model Context Protocol client over stdio or HTTP:

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

Client setup, data directory and the one-writer rule: MCP integration.

The five-minute quickstart walks through ingest, search, a SQLite FTS5 comparison and encryption in Rust, Python and Node, and CI runs that code on every pull request. For a whole agent memory with no embeddings and no network, run cargo run --example demo-offline-agent.

Why is it called "holographic"?

In a hologram, every fragment of the plate carries a blurry copy of the whole picture. Cut it in half and you get the whole picture at lower resolution, not half a picture. Holographic Reduced Representations and Vector Symbolic Architectures (VSA) give memory that property:

• Bind two vectors (here, XOR of sparse bit sets) to tie a role to a filler: capital ⊗ paris. Binding again with the role recovers a noisy copy of the filler.
• Bundle many bound pairs into one vector of fixed size. The result stays similar to every part, so one vector can hold a whole record, with no single bit holding any one fact.
• Recall by resonance. Present a noisy cue and the nearest stored pattern wins (similarity search, Hopfield cleanup). Damaging the vector degrades every item a little instead of deleting a few, so recall falls off gradually under noise.

You can watch it happen in a few lines (a union bundle of 100 items, damaged step by step): cargo run --release --manifest-path examples/quickstart/rust/Cargo.toml --bin holographic.

What is literally that here: the sparse hypervector type and its bind, bundle and permute operations; the relational "meaning memory" (triples stored as bound composites, multi-hop queries, Hopfield cleanup); the union-bundle membership test and the resonator network (both behind the experimental feature).

What is conventional engineering: document search (stemmed BM25 plus exact cosine; it does not read the hypervectors), the graph and inverted-file vector indexes, the memory API, the journaled storage and the servers. No holographic behavior is claimed for these. The longer version, with the tested numbers, is in Concepts.

What ships today

Every capability above except document search and the vector index is behind a Cargo feature or runtime option that is off by default; Cargo features lists them all.

Architecture

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

Module map: docs/ARCHITECTURE.md.

Limits

• Not anonymous. Hypervector sketches and term counts are not encryption; anyone with a store can encode candidate text and compare. storeText: false keeps term counts, IDs and embeddings, so it is not a privacy control.
• Document search is conventional. It does not use the hypervectors; the holographic parts are the algebra and the meaning memory.
• One writer per store. A second writing process fails at open with a lock error.
• Capacity numbers are points, not guarantees, and are stated only over the tested range (capacity).
• Benchmark results are single machines. Conditions are in each results file; the single-core ann-benchmarks run and the VIBE high-recall points are losses (see Where it's behind).
• Masking is obfuscation. Client-side vector masking preserves every pairwise similarity.
• A store is a directory and HmsCore::new(.., None, ..) uses the current directory.

Full statement: docs/PRIVACY.md. Report vulnerabilities privately via SECURITY.md.

Contributing

CONTRIBUTING.md: setup, the checks CI runs, DCO sign-off (git commit -s, no CLA). Start with a good first issue or Discussions. See the Code of Conduct. Benchmark changes regenerate the results file they touch; the README cites files, not remembered figures.

License

Apache-2.0. See LICENSE. Use, modify and embed it in open-source or proprietary software, including network services, with no copyleft obligation. Releases up to and including crate 0.6.1 were published under AGPL-3.0-or-later and stay available under those terms.