holographic-vsa 0.6.1

Holographic Memory System (HMS)

Privacy-preserving semantic search and associative memory — runs entirely on your machine.

Install · Quick Start · Why HMS? · Features · Performance · Architecture · Provenance · Production Readiness

HMS is a high-performance vector memory engine for Rust and Node.js. It implements Vector Symbolic Architectures (VSA) using Binary Spatter Code (BSC) to deliver semantic search, analogical reasoning, relational knowledge graphs, and associative memory — with no external API calls, no cloud dependencies, and no data leaving your device. Optional features add encrypted storage, signed audit logs, credential-gated agent access, and COSE/SCITT/C2PA provenance.

Developed by WritersLogic

Python SDK (experimental)

holographic-sdk (in bindings/python/holographic-sdk) is an HTTP client with adapters for LangChain, LlamaIndex, Haystack, Semantic Kernel, CrewAI, Phidata, PydanticAI, SmolAgents, DSPy, and Embedchain. It expects an HMS-backed HTTP service exposing /api/v1/documents and /api/v1/query; this repository does not ship that service, so the SDK is only useful against a server you provide.

Rust & Node.js Core Installation

The core backend is implemented in pure Rust.

cargo add holographic-memory
# Or for Node:
npm install holographic-memory

# Rust
[dependencies]
holographic-memory = "0.6"

Security Features

All of these are opt-in Cargo features; default = []. See SECURITY.md and PRIVACY.md for the threat model and limits.

• Encrypted storage and signed audit log (security): AES-256-GCM over arena payloads and index caches with an Argon2id-derived key; Ed25519-signed audit entries.
• Client-side vector masking (security, core::mask::VectorMask): an Argon2id-keyed secret permutation applied before vectors leave the client, so a remote store can rank them without the original coordinates. This is obfuscation, not encryption and not homomorphic encryption: it preserves and therefore reveals all pairwise similarities, and known plaintext/masked pairs progressively reveal the key.
• Credential-gated agent access (provenance, core::provenance::access): agents are admitted by W3C Verifiable Credentials with an eddsa-jcs-2022 proof from an issuer did:key the host explicitly trusts, with expiry and revocation. HmsCore::query_as enforces a read grant. The host must still authenticate that a caller controls the DID it presents.
• Provenance (provenance, provenance-scitt): COSE_Sign1 signed statements, SCITT registration, and C2PA manifests in JUMBF.

Not implemented: PoSME receipts, RATS attestation verification, did:web resolution for access credentials, and any form of search over encrypted data.

Quick Start

Document Search

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

async function main() {
  const hms = new HolographicMemorySystem(16384, './documents-v2');
  const memory = new DocumentMemory(hms);
  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(console.error);

Writing the same document ID replaces its chunks atomically. Results include source byte offsets; memory.delete(id) removes every chunk. See resource limits and migration. Existing stores without the new embedding schema require re-encoding from original sources.

Local Embeddings and Reranking

Install @huggingface/transformers and obtain compatible ONNX model files in local directories. The factories below never download models. Use actual artifact revisions and configure the store from the returned embedding space; it also fingerprints pooling, prefixes, and dtype.

const { createLocalEmbedder, createLocalReranker, DocumentMemory } = require('holographic-memory/semantic');

const embedder = await createLocalEmbedder({
  modelPath: process.env.HMS_EMBEDDING_DIR,
  modelId: 'Xenova/all-MiniLM-L6-v2',
  revision: process.env.HMS_EMBEDDING_REVISION,
  dtype: 'q8',
});
const rerank = await createLocalReranker({ modelPath: process.env.HMS_RERANKER_DIR, dtype: 'q8' });
const hms = new HolographicMemorySystem(16384, './semantic-v2', {
  embeddingModel: embedder.space.model,
  embeddingRevision: embedder.space.revision,
  embeddingDimensions: embedder.space.dimensions,
});
const memory = new DocumentMemory(hms, { embedder, rerank });
await memory.memorize({ id: 'vehicle', text: 'The automobile needs a mechanic.', sourceUri: 'notes.md' });
console.log(await memory.search('Where can I get my car repaired?', { k: 3 }));
await memory.flush();
await rerank.dispose();
await embedder.dispose();

Run the complete document example or the reproducible quality and latency evaluation. Exact dense cosine and BM25 scan eligible chunks before optional reranking; benchmark your corpus before assuming a deployment capacity.

Relational Knowledge (Meaning Memory)

const hms = new HolographicMemorySystem(16384, './knowledge-v2', {
  meaningEnabled: true,
});

await hms.memorizeTriplet('t1', 'paris',  'capital_of', 'france');
await hms.memorizeTriplet('t2', 'berlin', 'capital_of', 'germany');
await hms.memorizeTriplet('t3', 'john',   'father',     'mark');
await hms.memorizeTriplet('t4', 'mark',   'father',     'bob');

// "Paris is the capital of which country?"
const result = await hms.structuralQuery(['paris'], ['capital_of'], 'object');
console.log(result[0].entityId);   // 'france'
console.log(result[0].confidence); // confidence depends on the stored knowledge

// Follow two outgoing father relations: john → mark → bob.
const descendants = await hms.multiHopQuery('john', ['father', 'father']);
console.log(descendants[0].entityId);  // 'bob'

Why HMS?

• Local lexical and semantic document retrieval with passages, versions, and metadata filters.
• Vector-symbolic composition and structured multi-hop queries in one native engine.
• Transactional mutations, verified compaction generations, and explicit index maintenance.
• Optional encryption, audit, and provenance features with runtime capability reporting.

# Compositional algebra, analogies, interference, sequences
cargo run --release --features experimental --bin hms-research-bench -- --dim 16384 --density 256 --json

# Capacity walls, throughput, compression
cargo run --release --features experimental --bin hms-scaling -- --dim 16384 --density 256 --json

# Full 8-section suite
cargo run --release --features experimental --bin hms-benchmark-suite -- --dim 16384

# Machine-readable recall and latency regression report
cargo run --release --bin hms-eval -- \
  --vectors 1500 --queries 100 --dimensions 16384 --assert-min-recall 0.90

# Read metadata or verify every frame
cargo run --release --bin hms-admin -- inspect ./store
cargo run --release --bin hms-admin -- verify ./store

# Create a locked, verified, atomically published copy
cargo run --release --bin hms-admin -- migrate ./store ./store-copy

const hms = new HolographicMemorySystem(16384, './storage', {
  meaningEnabled: true,
  meaningBeta: 24.0,         // Hopfield temperature
  meaningMaxFanout: 40,      // Algebraic vs materialized path threshold
  meaningMaxHopDepth: 10,    // Multi-hop chain limit
});

let mut config = HmsConfig::default();
config.meaning.enabled = true;
config.cognition.enabled = true;
config.cognition.interval_secs = 60;
config.meaning.beta = 24.0;
config.meaning.algebraic_max_fanout = 40;

[dependencies]
holographic-memory = { version = "0.6", features = ["provenance"] }

use holographic_memory::HmsCore;

let hms = HmsCore::new(16384, Some("./storage".into()), None)?;

let record = hms.create_fact_provenance("fact-001", b"Paris is the capital of France", None)?;
assert!(record.cose_envelope.is_some());

let result = hms.verify_fact_provenance(&record)?;
assert!(result.valid);

let manifest = hms.create_self_manifest(Some("My Knowledge Store"))?;
assert!(manifest.jumbf_manifest.is_some());

cargo run --features provenance --example verify_cogmem_sample

Part of the Agent-Provenance Stack

HMS is one component of the WritersLogic verifiable agent-provenance pipeline — agent identity, memory, reasoning, and signed output, cryptographically bound end to end.

All four share one substrate — COSE_Sign1 / SCITT (Ed25519) and W3C DID — specified in UNIFIED-PROVENANCE.md.

Development

# Build (set local cargo dirs to avoid permission issues)
export CARGO_HOME=$(pwd)/.cargo_home
export CARGO_TARGET_DIR=/tmp/hms-target
npm run build

# Test
cargo test --lib

Security

Lossy vectors are not encryption or anonymization. Document ingestion stores source passages by default. Enable encryption when required, inspect securityStatus(), and read PRIVACY.md for precise guarantees and limitations. For vulnerability reporting see SECURITY.md.

Licensing (Dual-License Model)

Holographic Memory System (HMS) uses a Dual-Licensing model:

1. Open Source (AGPL-3.0): The core engine is free to use and modify for open-source projects, personal use, or internal evaluation, provided you comply with the GNU Affero General Public License v3.0. Note that using HMS as a backend for a proprietary service over a network requires you to open-source your service under AGPL, or purchase a commercial license.
2. Commercial License (WritersLogic Enterprise): For companies building closed-source, proprietary software, you must purchase a Commercial License. This bypasses the AGPL restrictions and provides production SLA support.

Contact licensing@writerslogic.com for enterprise inquiries.