Quickstart¶

git clone https://github.com/writerslogic/holographic-memory
cd holographic-memory
cargo run --release --manifest-path examples/quickstart/rust/Cargo.toml

git clone https://github.com/writerslogic/holographic-memory
cd holographic-memory
cargo build --release --features server --bin hms-server
HMS_API_KEY=quickstart target/release/hms-server --input-dim 384 &
HMS_API_KEY=quickstart uv run --with bindings/python/holographic-sdk \
    python examples/quickstart/python/quickstart.py

git clone https://github.com/writerslogic/holographic-memory
cd holographic-memory
npm ci --omit=optional && npm run build
node examples/quickstart/node/quickstart.mjs

    // 1. Ingest. A store is a directory (`None` would use the current directory); it persists
    // there and reopens with the same arguments.
    let store_dir = tempfile::tempdir()?;
    let hms = HmsCore::new(
        DIMENSIONS,
        Some(store_dir.path().display().to_string()),
        None,
    )?;
    let start = Instant::now();
    let inputs: Vec<DocumentInput> = corpus.iter().map(to_input).collect();
    hms.memorize_documents(inputs)?;
    println!(
        "ingested {} documents in {:.1?}",
        corpus.len(),
        start.elapsed()
    );

# 1. Ingest. The server keeps one store per tenant; you send the text and a vector per document.
docs = [
    {"id": d["id"], "vector": toy_embed(d["text"]), "text": d["text"], "metadata": {"title": d["title"]}}
    for d in corpus
]
client = HolographicClient(url=URL, api_key=API_KEY, tenant_id=tenant)
started = time.perf_counter()
client.add_documents(docs)
print(f"ingested {len(docs)} documents in {(time.perf_counter() - started) * 1000:.1f} ms")

// 1. Ingest. A store is a directory; it persists there and reopens with the same arguments.
const memory = new DocumentMemory(new HolographicMemorySystem(4096, mkdtempSync(join(tmpdir(), 'hms-quickstart-'))))
const started = performance.now()
await memory.ingest(corpus.map(toInput))
console.log(`ingested ${corpus.length} documents in ${(performance.now() - started).toFixed(1)} ms`)

    // The same corpus in SQLite FTS5 (bm25 ranking), for comparison.
    let db = Connection::open_in_memory()?;
    db.execute_batch("CREATE VIRTUAL TABLE docs USING fts5(id UNINDEXED, text);")?;
    for doc in &corpus {
        db.execute(
            "INSERT INTO docs (id, text) VALUES (?1, ?2)",
            (&doc.id, &doc.text),
        )?;
    }

    // 2. Search both engines with the same queries.
    println!("\n{:<58} {:<9} {:<9} expected", "query", "HMS", "FTS5");
    let (mut hms_hits, mut fts_hits) = (0, 0);
    for q in &queries {
        let query = q["query"].as_str().context("query")?;
        let expect = q["expect"].as_str().context("expect")?;
        let options = SearchOptions {
            k: Some(3),
            ..Default::default()
        };
        let results = hms.search_documents(query, &options)?;
        let hms_top = results
            .first()
            .map_or("-", |r| r.document_id.as_str())
            .to_owned();
        let fts_top: String = db
            .query_row(
                "SELECT id FROM docs WHERE docs MATCH ?1 ORDER BY bm25(docs) LIMIT 1",
                [fts5_query(query)],
                |row| row.get(0),
            )
            .unwrap_or_else(|_| "-".to_owned());
        hms_hits += usize::from(hms_top == expect);
        fts_hits += usize::from(fts_top == expect);
        println!("{query:<58} {hms_top:<9} {fts_top:<9} {expect}");
    }
    println!(
        "top-1 correct: HMS {hms_hits}/{n}, FTS5 {fts_hits}/{n}",
        n = queries.len()
    );
    ensure!(
        hms_hits >= 5,
        "HMS found the expected article for only {hms_hits} queries"
    );

# The same corpus in SQLite FTS5 (bm25 ranking), for comparison.
db = sqlite3.connect(":memory:")
db.execute("CREATE VIRTUAL TABLE docs USING fts5(id UNINDEXED, text)")
db.executemany("INSERT INTO docs (id, text) VALUES (?, ?)", [(d["id"], d["text"]) for d in corpus])

# 2. Search both engines with the same queries.
print(f"\n{'query':<58} {'HMS':<9} {'FTS5':<9} expected")
hms_hits = fts_hits = 0
for q in queries:
    matches = client.query(toy_embed(q["query"]), top_k=3)["matches"]
    hms = matches[0]["id"] if matches else "-"
    row = db.execute(
        "SELECT id FROM docs WHERE docs MATCH ? ORDER BY bm25(docs) LIMIT 1", (fts5_query(q["query"]),)
    ).fetchone()
    fts = row[0] if row else "-"
    hms_hits += hms == q["expect"]
    fts_hits += fts == q["expect"]
    print(f"{q['query']:<58} {hms:<9} {fts:<9} {q['expect']}")
print(f"top-1 correct: HMS {hms_hits}/{len(queries)}, FTS5 {fts_hits}/{len(queries)}")
assert hms_hits >= 4, f"HMS found the expected article for only {hms_hits} queries"

// The same corpus in SQLite FTS5 (bm25 ranking), for comparison.
const db = new DatabaseSync(':memory:')
db.exec('CREATE VIRTUAL TABLE docs USING fts5(id UNINDEXED, text)')
const insert = db.prepare('INSERT INTO docs (id, text) VALUES (?, ?)')
for (const doc of corpus) insert.run(doc.id, doc.text)
// FTS5 treats a bare multi-word query as AND; OR of the words is the fair lexical baseline.
const fts5Query = query => query.split(/[^\p{L}\p{N}]+/u).filter(Boolean).map(w => `"${w}"`).join(' OR ')
const ftsTop = db.prepare('SELECT id FROM docs WHERE docs MATCH ? ORDER BY bm25(docs) LIMIT 1')

// 2. Search both engines with the same queries.
console.log(`\n${'query'.padEnd(58)} ${'HMS'.padEnd(9)} ${'FTS5'.padEnd(9)} expected`)
let hmsHits = 0
let ftsHits = 0
for (const { query, expect } of queries) {
  const [hit] = await memory.search(query, { k: 3 })
  const hms = hit?.documentId ?? '-'
  const fts = ftsTop.get(fts5Query(query))?.id ?? '-'
  hmsHits += hms === expect
  ftsHits += fts === expect
  console.log(`${query.padEnd(58)} ${hms.padEnd(9)} ${fts.padEnd(9)} ${expect}`)
}
console.log(`top-1 correct: HMS ${hmsHits}/${queries.length}, FTS5 ${ftsHits}/${queries.length}`)
assert.ok(hmsHits >= 5, `HMS found the expected article for only ${hmsHits} queries`)

    // Hits carry the passage and its byte range in the source text.
    let hit = &hms.search_documents("asylum from persecution", &SearchOptions::default())?[0];
    println!(
        "\n{} bytes {}..{} score {:.3}: {}",
        hit.document_id,
        hit.start_byte,
        hit.end_byte,
        hit.score,
        hit.text.as_deref().unwrap_or("")
    );

# Hits carry the stored text, metadata and the exact cosine score.
top = client.query(toy_embed("asylum from persecution"), top_k=1)["matches"][0]
print(f"\n{top['id']} score {top['score']:.3f}: {top['text']}")

// Hits carry the passage and its byte range in the source text.
const [hit] = await memory.search('asylum from persecution')
console.log(`\n${hit.documentId} bytes ${hit.startByte}..${hit.endByte} score ${hit.score.toFixed(3)}: ${hit.text}`)

    // 3. Encrypt: the same corpus in a persistent store with AES-256-GCM (Argon2id key).
    let secret_dir = tempfile::tempdir()?;
    let secret_path = secret_dir.path().display().to_string();
    let mut config = HmsConfig::default();
    config.security.encryption_enabled = true;
    config.security.encryption_passphrase = Some("correct horse battery staple".into());

    let sealed = HmsCore::new(DIMENSIONS, Some(secret_path.clone()), Some(config.clone()))?;
    sealed.memorize_documents(corpus.iter().map(to_input).collect())?;
    sealed.flush()?;
    println!("\nsecurity status: {}", sealed.security_status());
    drop(sealed);
    let needle = b"periodic holidays with pay";
    let leaks = files_containing(secret_dir.path(), needle)?;
    println!("encrypted store, files holding the passage: {leaks:?}");
    // With encryption on, no store file may hold the passage text, the file-backed text segment
    // (`documents.text`) included.
    ensure!(leaks.is_empty(), "plaintext passage found in {leaks:?}");
    println!("no store file holds the passage text");

    let reopened = HmsCore::new(DIMENSIONS, Some(secret_path.clone()), Some(config.clone()))?;
    let hit = &reopened.search_documents("paid holidays", &SearchOptions::default())?[0];
    println!("reopened with the passphrase, top hit: {}", hit.document_id);
    drop(reopened);

    config.security.encryption_passphrase = Some("wrong passphrase".into());
    let Err(error) = HmsCore::new(DIMENSIONS, Some(secret_path), Some(config)) else {
        anyhow::bail!("opening with the wrong passphrase must fail");
    };
    println!("opening with a wrong passphrase fails: {error}");
    ensure!(
        !error.to_string().contains("already open"),
        "failed for the wrong reason: {error}"
    );

# 3. Protect. hms-server has no encryption at rest, so the client masks vectors with a key the
# server never sees. This is obfuscation, not encryption: the server still learns every pairwise
# similarity and stores text and metadata in plaintext (docs/SERVER.md).
masked = HolographicClient(
    url=URL, api_key=API_KEY, tenant_id=tenant + "-masked", zero_trust_key="correct horse battery staple"
)
masked.add_documents(docs)
plain_vec = toy_embed("paid holidays")
assert masked.encrypt_vector(plain_vec) != plain_vec
top = masked.query(plain_vec, top_k=1)["matches"][0]
print(f"masked store, top hit for 'paid holidays': {top['id']}")
assert top["id"] == "udhr-24"

wrong = HolographicClient(url=URL, api_key=API_KEY, tenant_id=tenant + "-masked", zero_trust_key="wrong key")
top = wrong.query(toy_embed("paid holidays"), top_k=1)["matches"][0]
print(f"same store queried with the wrong key, top hit: {top['id']}")
assert top["id"] != "udhr-24"

// 3. Encrypt: the same corpus in a persistent store with AES-256-GCM (Argon2id key).
const needle = Buffer.from('periodic holidays with pay')
const filesHolding = dir => readdirSync(dir, { recursive: true, withFileTypes: true })
  .filter(entry => entry.isFile() && readFileSync(join(entry.parentPath, entry.name)).includes(needle))
  .map(entry => entry.name)
  .sort()

const sealedDir = mkdtempSync(join(tmpdir(), 'hms-sealed-'))
execFileSync(process.execPath, [fileURLToPath(import.meta.url), '--ingest', sealedDir, 'encrypted'], { stdio: 'inherit' })
const leaks = filesHolding(sealedDir)
console.log(`\nencrypted store, files holding the passage: ${JSON.stringify(leaks)}`)
// With encryption on, no store file may hold the passage text, the file-backed text segment
// (`documents.text`) included.
assert.deepEqual(leaks, [])
console.log('no store file holds the passage text')

// A wrong passphrase must not open the store; the right one must.
const wrong = { ...sealedConfig, encryptionPassphrase: 'wrong passphrase' }
assert.throws(() => new HolographicMemorySystem(4096, sealedDir, wrong), error => {
  console.log(`opening with a wrong passphrase fails: ${error.message}`)
  return !/already open/.test(error.message)
})
const reopened = new HolographicMemorySystem(4096, sealedDir, sealedConfig)
assert.equal(reopened.securityStatus().encryptionActive, true)
const [again] = await new DocumentMemory(reopened).search('paid holidays')
console.log(`reopened with the passphrase, top hit: ${again.documentId}`)
assert.equal(again.documentId, 'udhr-24')