Generated banner for WARM
Generated logo for WARM

WARM

Memory serverOfficial Writerslogic project

Created by Writerslogic

Published in writerslogic/warm. Publisher page

27 GitHub stars

What it is

WritersLogic Adaptive Retention & Memory (WARM): local document search (BM25 + embedding cosine) and vector-symbolic associative memory.
— the description by Writerslogic

AutoGineer overview, from the brain’s own files

WARM (WritersLogic Adaptive Retention & Memory) is a local-first memory engine designed to provide AI agents and applications with persistent storage and retrieval. It combines traditional document search—using stemmed BM25 and vector-based cosine similarity—with a vector-symbolic layer for associative memory and multi-hop queries. The system is built in Rust and can be deployed as an embedded library, an HTTP server, or an MCP server, allowing it to integrate with various agent hosts and development environments. It emphasizes local control, offering optional encryption and provenance features while avoiding external service calls or telemetry.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

The system stores text, vectors, and facts in a local directory. It uses a hybrid approach where document search combines chunking and BM25 with vector embeddings. The vector-symbolic layer utilizes sparse hypervectors to support associative memory, triples, and multi-hop queries. It provides an API for memory management including remember, recall, and forget operations, with support for source provenance and atomic storage updates.

Folders
FolderRoleFiles
.githubagent-config37
assetsattachments10
docsdocs1850
examplesexamples47
scriptsscripts77
srcsource-code327
teststests362
benchesfolder7
benchmarksfolder2898
bindingsfolder273
deployfolder18
figuresfolder6
fuzzfolder54
integrationsfolder225
interopfolder3
notebooksfolder3
npmfolder1
proptest-regressionsfolder1
schemasfolder9

The agent reads

Requirements

Runtimes: Node.js, Python >=3.9, Rust

Databases: SQLite

API keys (by name): WARM_API_KEY

Works with: Gemini CLI

Set it up

  1. This brain runs code automatically: 1 hook (claude-code), 1 script. Review benchmarks/results/sbg_positions_development/setup.sh, integrations/editors/claude-code/plugin/hooks/hooks.json before opening the folder in Claude Code. No step below turns a hook on for you.

    • benchmarks/results/sbg_positions_development/setup.sh: sh benchmarks/results/sbg_positions_development/setup.sh
    • integrations/editors/claude-code/plugin/hooks/hooks.json: node
  2. Not scanned by AutoGineerThe author’s README also describes installing it from a clone of its repository. Read its install section: AutoGineer did not scan that path. https://github.com/writerslogic/warm/blob/e176d5572dd86bf2233bcb120e3a485dc109ea3a/README.md#get-started
  3. Not scanned by AutoGineerThe author’s README also describes installing it as the npm package writerslogic-warm. Read its install section: AutoGineer did not scan that path. https://github.com/writerslogic/warm/blob/e176d5572dd86bf2233bcb120e3a485dc109ea3a/README.md#get-started
  4. Created by Writerslogic. Published in writerslogic/warm. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Integrating memory into an AI agent via the MCP server.
  • Building local-first applications that require embedded search and storage.
  • Providing a multi-tenant memory service via the HTTP server.
  • Using the Rust library for in-process memory management.
“Remember that the project deadline is Friday.”
The agent stores the fact with associated metadata, making it available for future retrieval.
“Recall information about the project deadline.”
The agent retrieves the stored fact using hybrid search and provides the information with source provenance.

Documentation by Writerslogic

<img src="https://raw.githubusercontent.com/writerslogic/warm/main/assets/crystal-halo/crystal-detailed-static.png" alt="WARM logo" width="96" align="left">

WARM

Local memory for AI agents and applications.

WARM (WritersLogic Adaptive Retention & Memory) gives agents persistent memory, full-text and vector search, and source provenance in one embeddable Rust engine. Use it inside your application, through HTTP, or from an MCP client, with storage on infrastructure you control.

Image: CI Image: MSRV 1.89 Image: OpenSSF Scorecard Image: OpenSSF Best Practices Image: License: Apache-2.0 Image: WARM MCP server: quality and maintenance score on Glama

Website · Docs · Get started · Standards and provenance · Evaluation · Capabilities · Limits · Contribute

<br clear="left">

What it is

WARM is a Rust library that stores text, vectors and facts in a directory on your machine and finds them again. It ships with optional Node.js, C, WASM and UniFFI bindings, an HTTP server with portable JavaScript and Python clients, and an MCP server. The embedded engine makes no service calls or telemetry requests. HTTP clients connect to the server you configure; model stages are opt-in.

CapabilityWhat you get
Document searchChunking, stemmed BM25 over blocked postings, Boolean and phrase queries, hybrid fusion with embeddings you supply, metadata filters, byte offsets
Vector indexGraph index with a memory-mapped vertex file, an updatable delta for inserts and deletes, optional query-aware routing trained on sample queries
Memory APIremember, recall, forget and explain with time validity and supersession; conversation memory with source provenance
StorageAtomic replace and delete, crash-safe journal and checkpoints, verified compaction, one writer per store
SecurityOptional AES-256-GCM storage encryption with documented coverage and limits, signed audit log, COSE/SCITT provenance
Vector-symbolic layerSparse hypervectors with bind, bundle and permute, triples with multi-hop queries, Hopfield cleanup

Who it's for

You are buildingWhat you get
An agent or assistant that needs memoryA memory API with forgetting that removes facts from the store, and an MCP server for editors and agent hosts
A local-first or offline appEmbedded search and storage in one directory, with no server process and optional encryption
A service that needs vector or text searchwarm-server over HTTP with tenants and scoped keys, or the library in-process

Get started

For an editor or agent host, start with the MCP integration. For an application, choose the Rust library or HTTP server below. WARM runs locally or on your own infrastructure; this repository does not provide a managed cloud service.

To try the offline memory demo from source:

git clone https://github.com/writerslogic/warm
cd warm
cargo run --release --example demo-offline-agent

<details open> <summary><strong>Rust</strong></summary>

From your own Rust project, add the current Apache-2.0 source. The crate is warm-rust; the library is imported as writerslogic_warm. The MSRV is Rust 1.89; local-models and --all-features need Rust 1.94 or newer.

cargo add warm-rust

The historical v0.6.1 source remains AGPL-3.0-or-later; it is available from that Git tag, not as a warm-rust 0.6.1 release on crates.io.

use writerslogic_warm::{DocumentInput, WarmCore, SearchOptions};

let dir = tempfile::tempdir()?;
let warm = WarmCore::new(4096, Some(dir.path().display().to_string()), None)?;
warm.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 = warm.search_documents("restore backups", &SearchOptions::default())?;
println!("{} {:?}", hits[0].document_id, hits[0].source_uri);

Rust API change in 0.6.6 (0.6.5 returns these values directly): WarmCore::query, query_batch, and analyze_components return Result. Handle the result with ? or an explicit error branch; deferred-encoding failures no longer become successful partial query results. get_document, list_documents, get_document_info, and list_document_info also return Result; retained-text and checkpoint decoding failures propagate instead of panicking, and reads no longer hydrate the entire checkpoint or hold store locks during text I/O.

</details>

<details> <summary><strong>JavaScript and TypeScript: portable client</strong></summary>

warm-sdk 0.2.1 is the portable HTTP client for a separately running warm-server. It has no native binaries or runtime dependencies and uses standard Fetch and Web Streams APIs (Node 18 or newer). Installing or importing it does not load the embedded engine or download models. For a published release, install the client in your application:

npm install [email protected]

Check the available npm versions. To build the client from this checkout:

npm ci --prefix bindings/js/warm-sdk
npm run build --prefix bindings/js/warm-sdk

In your application, install that directory with npm install /absolute/path/to/warm/bindings/js/warm-sdk.

Start the server in a separate terminal:

cargo build --release --features server --bin warm-server
WARM_API_KEY=change-me target/release/warm-server --input-dim 384
import { WarmClient } from 'warm-sdk'

const warm = new WarmClient({
  url: process.env.WARM_URL ?? 'http://127.0.0.1:8080',
  apiKey: process.env.WARM_API_KEY, tenantId: 'demo',
})
await warm.memory.remember('Restore deleted documents from verified backups.', {
  id: 'backups', metadata: { project: 'alpha' },
})
const hits = await warm.memory.recall('restore backups', { filter: { project: 'alpha' } })
console.log(hits[0]?.text)

Set WARM_API_KEY to the server's key before running the client. This memory example uses lexical retrieval and needs no embedding model. A runnable source example also checks retrieval and deletion in an isolated namespace:

WARM_URL=http://127.0.0.1:8080 WARM_API_KEY=change-me \
  node examples/quickstart/js-client/quickstart.mjs

See the client API and release availability. Browser deployments must permit the application's origin at the HTTP service boundary.

</details>

<details> <summary><strong>Node.js: optional embedded engine</strong></summary>

writerslogic-warm embeds the Rust engine in Node. For a published engine release, install it explicitly with npm's optional dependencies enabled:

npm install [email protected]

Check the available npm versions. To build from the cloned repository, with Rust installed:

npm ci --omit=optional
npm run build

The portable client and embedded engine are separate packages with different APIs. listDocuments supports scoped pruning. See the integration guide for source provenance, namespace isolation, dry runs and deletion limits.

const { WarmMemorySystem } = require('writerslogic-warm')
const { DocumentMemory } = require('writerslogic-warm/semantic')

async function main() {
  const dir = require('node:fs').mkdtempSync(require('node:path').join(require('node:os').tmpdir(), 'warm-readme-'))
  const memory = new DocumentMemory(new WarmMemorySystem(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) })

</details>

<details> <summary><strong>Server and Python</strong></summary>

The Python package warm-sdk is an HTTP client for warm-server, which stores vectors you supply. (warm-python, imported as writerslogic_warm, provides native vector indexes and phase vectors, but no document search.)

cargo build --release --features server --bin warm-server
WARM_API_KEY=change-me target/release/warm-server --input-dim 384 &
uv pip install warm-sdk
from writerslogic_warm_sdk import WarmClient

client = WarmClient(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.

</details>

<details> <summary><strong>MCP</strong></summary>

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

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

The MCP package is a separate launcher. To build the server from source:

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

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

For normalized content from multiple applications, see the organizational knowledge adapter.

</details>

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.

<a id="headline-results"></a> <a id="where-its-behind"></a>

Evaluation

Recorded results and limitations cover memory quality, text retrieval and vector search. Each result retains its workload, hardware, model, source revision and known losses. The full comparison and reproduction protocol provide the evidence for evaluating WARM on your own workload.

What ships today

CapabilityStatusDocumented limit
Hybrid document search (BM25 + exact cosine, filters, byte offsets)ShipsExact scan of eligible chunks; benchmark your corpus before assuming capacity (guide)
Boolean lexical search (+required, -excluded, quoted phrases)ShipsFlat queries only, no nesting; an empty or only-excluded query matches nothing (design)
Atomic replace/delete, crash-safe journal, verified compaction, process lockShipsOne writer per store; compaction is not secure erasure
Vector index (qgraph vertex graph, memory-mapped)ShipsBuild time and serving RSS behind hnswlib on SIFT-1M (gaps)
Updatable vector index (durable delta for inserts and deletes)ShipsSingle writer; format in VECTOR-UPDATES.md
Query-aware graph routing (trained on sample queries)Ships (opt-in)Needs representative training queries; tested on VIBE llama and yi (report)
Memory API: remember, recall, forget, explainShipsForgetting removes a fact from the store; it does not cover what a model inferred (docs)
Conversation memory (conversation-memory)ShipsBounded context with exact source provenance; native recall not yet benchmarked on LongMemEval end to end
Meaning memory: triples, multi-hop, Hopfield cleanupShips (runtime opt-in)Tested on synthetic and 2,120-fact sets (research_bench_16384_256.json)
Union-bundle membership (experimental)ResearchAt D = 16,384: positive gap to N = 500 (4% false positives), tested to 2,500 (benchmark_scaling_results.json)
Sparse vector index (memorize_vector)ExperimentalNot competitive with HNSW (results)
Encrypted stores (security)ShipsAES-256-GCM, Argon2id; covers the log, index caches and the text segment. Metadata, file names and sizes are not encrypted
Signed audit log, credential-gated access, COSE/SCITT/C2PA (provenance)ShipsHost must authenticate DIDs; PoSME, RATS, did:web not implemented
On-device models (local-models: Qwen3 embed/rerank/LLM)ShipsLocal weights only; never downloads
warm-server HTTP API, multi-tenant (server)ShipsSingle node; TLS, per-tenant scoped keys (guide)
MCP server (mcp: warm-mcp, stdio and HTTP)ShipsEncryption needs security; semantic recall needs local-models
JavaScript/TypeScript client (warm-sdk 0.2.1)Source and release buildsPortable HTTP client; requires a separately running server
Embedded Node.js (writerslogic-warm 0.6.8)Source and release buildsEight optional native platform packages; separate from the client
C, Go, .NET, Java, Kotlin, Swift and WebAssembly bindingsSource availableRequire local builds; the language packages and native bundles are not yet published (runtime guides)
PythonHTTP client (warm-sdk); native vector indexes and phase vectors (warm-python)No in-process document search
Query-private search (private-search)ExperimentalFor searching an index someone else holds; hides the query vector from the scorer only (notes)

Optional engine capabilities use Cargo features or runtime configuration; Cargo features lists the build choices.

The compatibility policy defines API stability, deprecation windows and storage-format migration rules.

Architecture

flowchart TB
  subgraph bindings["Bindings and servers"]
    rust["Rust crate"]
    node["Node: writerslogic-warm (napi)"]
    ffi["C, WASM, UniFFI"]
    clients["JavaScript and Python: warm-sdk"]
    server["warm-server (HTTP)"]
    mcp["warm-mcp (stdio, HTTP)"]
  end
  subgraph engine["Engine API"]
    core["WarmCore: 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
  clients --> 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 WarmCore::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. The historical v0.6.1 source remains available under its AGPL-3.0-or-later license.

docs/PRIVATE-SEARCH.md

Private search (experimental)

Status: experimental prototype. It hides a query from the server. It is not encryption of stored data and must not be described as such. It has not been externally reviewed and has not been audited for constant-time behaviour. Do not rely on it to protect anything of value.

Code: src/core/private_query.rs, behind the Cargo feature private-search (off by default). Measurement: src/bin/research/private-query-bench.rs, results in benchmarks/results/private_query.json. A second layout for dense low-bit codes, which can score a chosen part of the database, is in src/core/private_query/clustered.rs; see Clustered ranking of dense codes.

This is unrelated to src/core/mask.rs, which is a keyed permutation of index labels (obfuscation).

What it does

A server stores sparse binary codes (EntangledHVec) in the clear. A client sends an encrypted query code; the server computes, for every stored row, an encryption of the intersection count |row ∩ query|; the client decrypts all N counts. The construction is the secret-key Regev scheme with a shared public matrix, as used by SimplePIR [1], applied to a sparse 0/1 database matrix instead of a PIR table. Tiptoe [2] uses the same idea for ranking.

With q = 2^32, Δ = floor(q / p), database X ∈ {0,1}^(N×D):

StepWhoComputation
PublicbothA ∈ Z_q^(D×n) expanded from a public 32-byte seed (ChaCha20)
Offlineserverhint H = X·A ∈ Z_q^(N×n); client downloads H
Queryclientfresh s ← Z_q^n, e ← χ^D; sends c = A·s + e + Δ·u
Answerservera = X·c (sum of c over each row's active indices)
Decodeclientscore_i = round((a_i − H_i·s) / Δ) mod p

A new secret is sampled for every query. QueryState is not Clone, decode takes it by value, and its Drop wipes the secret with zeroize, so one secret cannot serve two queries.

Threat model

Hidden: the content of the query code u (which indices are active and how many), from an honest-but-curious server that follows the protocol and sees A, the database, and any number of queries. This rests on the hardness of LWE with the parameters below. Every query is D words regardless of its weight.

Not hidden, not provided:

  • The database is fully visible to the server. Stored codes are plaintext. Nothing here protects a user's stored memories from whoever hosts them.

  • The client learns the score against every row, for every query. The database is not private from clients: D unit-vector queries reveal it entirely, and a client is not forced to send a binary query.

  • No protection against a malicious server returning wrong answers or a wrong hint. Answers are not authenticated; a wrong answer decodes to a wrong score with no error.

  • No hiding of query timing, query count, client identity, or network metadata. What the client does after decoding (for example fetching the top-scoring record) is outside the scheme and can reveal the query.

  • The implementation is not constant-time audited. The error sampler uses a table search with data-dependent timing, and the arithmetic has not been checked for secret-dependent timing.

  • Not externally reviewed. No formal proof accompanies this code; the security argument is the one in [1] and holds only to the extent this code matches that scheme.

  • The secret is wiped on drop; the thread-local RNG state and any copies the allocator or OS made (swap, core dumps) are not.

Parameters

ParameterValueSource
LWE dimension n1280lattice estimator [5], see below ([1] uses 1024)
Modulus q2^32 (wrapping u32)[1] Section 4.2
Error distribution χdiscrete Gaussian, σ = 6.4[1] Section 4.2
Secret distributionuniform over Z_q^n[1] Figure 2
Samples per query mD (16384 by default; at most 2^21 accepted)see below
Plaintext modulus p1024 (default)chosen here from the bound below
Error tail cut±77 = ceil(12σ)chosen here
Max row weight1023 (default)derived below

q and σ are SimplePIR's [1]: Section 4.2 of its USENIX Security 2023 text states n = 2^10, q = 2^32, discrete Gaussian with σ = 6.4, chosen "to have 128-bit security, according to modern lattice-attack-cost estimates"; Figure 2 samples s uniformly from Z_q^n and builds the query as A·s + e + Δ·u; Section 4.1 notes that A may be reused across many encryptions. The dimension is raised from SimplePIR's 1024 to 1280 because the lattice estimator does not reproduce the 128-bit figure at 1024.

Security estimate. The lattice estimator [5] (commit e4333d9, run under the pip-installable SageMath distribution passagemath-standard) on LWE with q = 2^32, a secret uniform mod q, a discrete Gaussian error and 2^21 samples, the most one query can publish (MAX_DIM; a clustered probe publishes C·d, 6,400 at C = 64, d = 100). Script benchmarks/private_search/lattice_estimate.py, output benchmarks/results/private_query_lattice_estimate.json. Bits are log2 of the estimated ring operations of the cheapest attack. "Default" is LWE.estimate with its default reduction cost model (MATZOV); "core-SVP" is LWE.estimate.rough, one sieving call of cost 2^(0.292 β) for BKZ block size β, the conservative count used for Kyber-style claims.

nσDefault, cheapest attack (bits)Core-SVP (bits)uSVP block sizeNote
10246.4121.5 (bdd)95.2326SimplePIR [1]; previous set
102411128.4 (bdd)102.5351YPIR [3], s = 11·sqrt(2π)
11526.4137.5 (bdd)111.8383
12806.4153.7 (bdd)128.8441this crate
14086.4170.3 (bdd)146.0500
20486.4257.1 (bdd)236.8811

The attacks run are uSVP, BDD (primal decoding), dual and dual-hybrid; Arora-GB, BKW and the BDD and meet-in-the-middle hybrids are skipped as slow and not competitive at this error and modulus. n = 1280 is the smallest multiple of 128 at which both columns exceed 128 bits; n = 1152 clears the default model but not core-SVP. As a cross-check, the Homomorphic Encryption Standard [6] (Table 1, BKZ.sieve, σ ≈ 3.2) allows log2 q up to 29 at n = 1024 and 56 at n = 2048 for 128 bits with a uniform secret, so q = 2^32 at n = 1024 is outside it; and the hand-written core-SVP script of the previous version (benchmarks/private_search/lwe_core_svp.py, n = 1024 only) agrees with the estimator's 95.2 and 102.5. These are estimates of known attacks under stated cost models, not proofs, and no quantum figure is claimed.

Not verified, stated so rather than assumed:

  • Tiptoe [2] ranks with different parameters: q = 2^64, n = 2048, σ = 81,920 and a ternary secret, stated as 128-bit for encrypted vectors of dimension up to 2^27 (Appendix C). They are not used here.

  • Deviations from the idealised scheme: the Gaussian is truncated at ±77 (tail mass below 2^-100) and its table is computed in f64 (about 2^-53 precision per entry), and A is pseudorandom (ChaCha20) rather than uniform. Their effect on the estimate was not analysed.

  • Multiple queries reuse A with independent secrets. The standard hybrid argument loses a factor equal to the number of queries; no concrete query budget was derived.

Correctness bound

For row i with active set R_i:

a_i − H_i·s = Σ_{j∈R_i} (c_j − A_j·s) = Σ_{j∈R_i} (e_j + Δ·u_j) = Δ·|R_i ∩ u| + E_i   (mod q)
E_i = Σ_{j∈R_i} e_j,   |E_i| ≤ |R_i| · 77

Rounding to the nearest multiple of Δ returns |R_i ∩ u| exactly when

  1. |R_i| < p, so the score, at most |R_i|, does not wrap modulo p; and

  2. |E_i| < Δ/2, guaranteed by 2 · |R_i| · 77 < Δ.

Because every error sample is bounded, this holds with certainty, not with a failure probability. The secret dimension n does not appear: H_i·s cancels exactly, so raising n changes neither bound. The largest admissible row weight is

w_max(p) = min(p − 1, floor((Δ − 1) / 154)),   Δ = floor(2^32 / p)

p = 1024 gives Δ = 2^22 and w_max = min(1023, 27235) = 1023. p = 65536 gives Δ = 65536 and w_max = 425, where the noise term binds. Params::new rejects a weight limit above w_max(p) and Server::new rejects any row heavier than the limit. The query weight is unconstrained: the error accumulates over the row's indices only. The bound is worst-case and loose; at weight 64 the typical |E_i| is about 6.4·sqrt(64) ≈ 51 against Δ/2 = 2,097,152.

Measured cost

From benchmarks/results/private_query.json, measured at the previous n = 1024, not re-run at 1280: hint bytes and the hint build, client encrypt and decode times scale with n (hint 4·n bytes per row, 5,120 at n = 1280); server answer time and query and answer bytes do not. D = 16384, row weight 64, release build, Apple M4, 10 rayon threads, crate 0.6.1. Medians of 20 queries (3 hint builds). One run on a machine that was not idle; the per-query maxima in the JSON are 10 to 200 times the medians, so treat these as indicative. Tested range is N = 10^3 to 10^5; nothing is claimed beyond it.

NServer answer (ms)Hint build (ms)Client encrypt (ms)Client decode (ms)Query (bytes)Answer (bytes)Hint (bytes)
1,0000.089.62.60.4565,5364,0004,096,000
10,0000.391363.30.8765,53640,00040,960,000
100,0000.888161.35.165,536400,000409,600,000

The hint is large: 4·n bytes per stored row (4,096 at n = 1024, 5,120 at 1280), 16 to 20 times the 256 bytes of a weight-64 row's plaintext indices, and 409.6 MB at N = 10^5 in the table (512 MB at n = 1280). The client must hold it and must download it again whenever the database changes. Server and client each also hold A, 64 MiB at D = 16384 and n = 1024 (43 ms to expand), 80 MiB at 1280. The answer is 4 bytes per row, so communication and client work are linear in N; this scheme returns all scores and does no private top-k selection.

Regenerate with:

cargo run --release --features private-search --bin private-query-bench

Tests

cargo test --features private-search private_query checks: decoded scores equal plaintext intersection counts (N = 2000, D = 16384, two matrix seeds × four data seeds × two queries); correctness at the maximum row weight for both regimes of the bound, and rejection one above it; rejection of malformed codes, wrong lengths and mismatched hints; that decoding with a different secret does not return the scores; that two encryptions of one code share almost no ciphertext words and ciphertext length does not depend on query weight; that the secret buffer is zeroed by the routine Drop calls; and the error sampler's bound and deviation.

These tests establish correctness and the stated mechanical properties. They cannot establish that the query is hidden; that rests on the LWE assumption and the parameter analysis in [1].

Clustered ranking of dense codes

Code: src/core/private_query/clustered.rs, same feature. Measurement: src/bin/research/private-rank-bench.rs. Recall and sizes: benchmarks/results/private_rank_sweep_100k.json and private_rank_sweep_1m.json. Protocol timings: private_rank_protocol_100k.json and private_rank_protocol_1m.json.

The database is N codes of d small signed integers in C clusters of at most S codes, laid out the way Tiptoe [2] lays out ranking: a matrix of S rows and C·d columns whose block k of row i is the i-th code of cluster k (zeros past the end of the cluster). The client keeps the C centroids, picks the P nearest clusters locally, and sends one ciphertext of C·d words per cluster, each under its own secret, encrypting the query code in that cluster's block and zeros elsewhere. The server multiplies the whole matrix by every ciphertext and returns S words per probe; the client decodes the P·S scores of its clusters with the hint H = M·A (S × n words). C = 1 scores the whole database. The LWE parameters and threat model are those above, plus: C, P and S are public and fixed, the cluster layout is public, and the client receives P·S scores, not ten.

Decoding. Row i has error E_i = Σ_j M_ij·e_j. A centred discrete Gaussian of parameter σ is σ-sub-Gaussian, and symmetric truncation keeps that, so P(|E_i| ≥ Δ/2) ≤ 2·exp(-(Δ/2)² / (2σ²·‖M_i‖²)). DenseParams takes a bound on ‖M_i‖², which DenseServer::new checks for every row, sets p to the smallest power of two above 2·d·Bx·Bu (Bx, Bu: database and query entry bounds), and rejects parameters whose union bound over a probe's S scores exceeds 2^-40. SimplePIR's δ = 2^-40 is per query; here it is per probe, so a query of P probes fails with probability at most P times the bound (2^-83 or less for every configuration in the tables). Decoding is correct with that probability, not with certainty, unless DenseParams::exact reports that the truncated worst case 2·77·C·d·Bx < Δ holds too (it does for the 1-bit rows below). Tests (cargo test --features private-search clustered) compare decoded scores with plaintext dot products for whole-database scoring, nine probes, entries at ±15 with the extreme scores ±d·Bx·Bu, and 1-bit codes; check that the error deviation over 2,048 rows at the norm bound is within 6% of σ·‖M_i‖; and check rejection of out-of-bound entries, oversized clusters, rows over the norm bound, bad cluster indices and mismatched hints.

Workload. glove-100-angular: the first N training rows and the first 1,000 test queries, unit-normalised and quantized to odd-integer levels, written database bits:query bits (1 bit is the sign, a bipolar hypervector; 4 bits is ±1 … ±15). k-means with 12 Lloyd iterations on a 100,000-row sample; cluster capacity 1.25× the mean size, each row placed in its nearest cluster with room. Recall@10 is measured against the exhaustive plaintext ranking of the same codes and is tie-aware: a returned code counts when its score reaches the tenth-best plaintext score. The recall columns come from the plaintext sweep over 1,000 queries (regenerated at n = 1280; every recall value equals the n = 1024 sweep's, since the plaintext ranking involves no LWE parameter); the protocol runs compared every decoded score of their 30 queries with the plaintext score and found no mismatch in any configuration (9.4 million scores at N = 10^6, C = 64, P = 16). For context, recall@10 against the exact f32 neighbours is also given; the 4:4 codes' own exhaustive ranking reaches 0.738 at N = 10^6.

Timing: Intel Core Ultra 9 185H ( Linux, AVX2, 22 rayon threads), release build, Rust 1.99.1, 2 warm-up and 30 timed queries per configuration, one run. Server time covers all P probes of one query, batched eight to a pass over the database; nothing is batched across queries. The tables are the n = 1280 runs. In the same locked session the n = 1024 build of the previous version ran the same configurations (order 1024, 1280, 1280, 1024 at 10^6; files in benchmarks/results/private_rank_n1280_ab/). Upload, download and the decoded scores are identical; server time is within run-to-run spread (C = 64, P = 16: 24.9 and 27.4 ms at n = 1024, 25.1 and 23.3 ms at 1280), as expected since the server never touches A or s. What grows with n is the client side: the hint by exactly 25%, the hint build from 1.3–1.5 s to 1.6–1.7 s, and decoding (C = 1: 57.5 and 53.1 ms to 65.7 and 66.2 ms). "Scored" is P·S/N, an upper bound on the share of rows whose scores the client receives: S is the fullest cluster's size and smaller clusters are padded, so the mean share is close to P/C. The server reads the whole database for every probe.

N = 10^6:

CodesCPScoredRecall@10, same codesRecall@10, f32Server ms, median [p10–p90]UploadDownloadHintClient prepare / decode msFailure bound per probe
4:411100%1.0000.7384.5 [3.8–5.3]400 B4.00 MB5,120 MB0.0 / 65.72^-5911
4:416431%0.8960.68810.7 [10.2–11.2]26 KB1.25 MB400 MB1.2 / 26.72^-387
4:432831%0.9350.70912.2 [10.3–15.9]102 KB1.25 MB200 MB2.4 / 32.52^-188
4:464816%0.9020.69410.4 [9.6–13.4]205 KB0.63 MB100 MB3.3 / 21.02^-87
4:4641631%0.9610.72325.1 [21.8–28.1]410 KB1.25 MB100 MB5.4 / 42.22^-87
1:4641631%0.9240.25223.9 [20.1–25.9]410 KB1.25 MB100 MB4.3 / 40.2exact

N = 10^5:

CodesCPScoredRecall@10, same codesRecall@10, f32Server ms, median [p10–p90]UploadDownloadHintClient prepare / decode msFailure bound per probe
4:411100%1.0000.7591.1 [0.8–1.6]400 B0.40 MB512 MB0.0 / 8.42^-6020
4:416863%0.9620.7401.8 [1.6–2.0]51 KB0.25 MB40 MB1.0 / 12.02^-392
4:432831%0.9120.7231.6 [1.5–1.7]102 KB0.13 MB20 MB1.5 / 9.42^-192
4:464816%0.8600.6941.6 [1.4–1.7]205 KB0.06 MB10 MB2.2 / 5.62^-91
4:4641631%0.9330.7323.3 [3.1–3.5]410 KB0.13 MB10 MB3.3 / 11.02^-91
1:4641631%0.8780.2693.3 [3.1–3.5]410 KB0.13 MB10 MB3.1 / 11.0exact

Offline per database version, besides the hint: the centroids (C·d floats, 25.6 KB at C = 64) and the public matrix A (C·d × n words, 33 MB at C = 64, expanded from a 32-byte seed in 3–10 ms on the test machine). Building the hint took 1.6–1.7 s at N = 10^6 for C ≥ 16 and 2.6 s at C = 1. Client prepare (fresh secrets and A·s + e for every probe) does not depend on the query and can run ahead; adding the query took under 0.01 ms. Results are (cluster, slot) positions; unless records are addressed by position, the client also needs the position-to-record map, 4 bytes per row (4 MB at N = 10^6). The sweep files cover C from 1 to 1,024 at 10^5 and 1 to 256 at 10^6, P from 1 to 64, and widths 1:4, 2:4 and 4:4; 4:4 codes fail the 2^-40 bound from C = 128 at 10^6 and C = 256 at 10^5 (params_valid: false).

Published systems, not like-for-like. SimplePIR [1] reports 10 GB/s/core of server throughput (DoublePIR 7.4) on 1 GB databases, single-threaded on an AWS c5n.metal, with a 121 MB hint (DoublePIR 16 MB) and 242 KB per query (DoublePIR 345 KB); it retrieves a record and does not rank. Tiptoe [2] searches 364 million pages with 145 core-seconds of server compute on 45 servers, 56.9 MiB per query of which 42.2 MiB (a per-query token that replaces the hint) moves before the query, and 2.7 s end to end. It scores a single cluster of about 50,000 documents with 192-dimensional signed 4-bit embeddings, puts 20% of documents in two clusters, and reports an average rank of 7.7 on MS MARCO (non-private embedding search 2.3, tf-idf 6.7). Its corpus is 364 times larger than the one here, it keeps no client hint, and it measures end-to-end quality rather than recall against its own codes.

The claim at N = 10^6. Targets: at most 100 ms of server time per query on one node, at most a few MB of online communication, the offline hint stated, and recall@10 of at least 0.9 against the plaintext ranking of the same codes. Kill criterion: no configuration meets all four at N = 10^6. It did not fire. On glove-100 quantized to 4-bit codes, C = 64, P = 16 meets all four: 25.1 ms median server time (28.1 ms at p90), 1.66 MB online (410 KB up, 1.25 MB down), a 100 MB hint per database version, recall 0.961. C = 32, P = 8 does too: 12.2 ms, 1.35 MB, a 200 MB hint, recall 0.935. C = 64, P = 8 (10.4 ms, 0.83 MB, 0.902) is within sampling error of the recall threshold over 1,000 queries and is not counted as a pass. Exact scoring of the whole database (C = 1) takes 4.5 ms of server time and 4 MB down but needs a 5,120 MB hint and 66 ms of client decoding. Limits of the result: one dataset, one machine, one run, 30 timed queries per configuration; recall against the share of the database scored depends on how well the data clusters, and on glove-100 the passing points score at most 31% of the rows (P/C = 25%). The query's hiding rests on LWE with n = 1280, q = 2^32, σ = 6.4: 2^153.7 by the lattice estimator's default model and 2^128.8 by core-SVP (see Parameters). Raising n rather than σ leaves every failure bound above unchanged. The alternative of YPIR's σ = 11 at n = 1024 reaches only 2^128.4 by the default model and 2^102.5 by core-SVP, and would multiply the failure-bound exponent by (6.4/11)² ≈ 0.34, which by that scaling (not measured) pushes the 4:4 rows at C = 64 past 2^-40. Not implemented: dropping low bits of the answer words (16-bit plaintext in a 32-bit word), and removing the hint with Tiptoe's token or a hintless scheme such as YPIR [3].

Regenerate with:

cargo run --release --features private-search,cli --bin private-rank-bench -- \
  sweep --data <glove-100-angular dir> --sizes 1000000 --clusters 1,16,32,64,128,256 \
  --out benchmarks/results/private_rank_sweep_1m.json
cargo run --release --features private-search,cli --bin private-rank-bench -- \
  protocol --data <glove-100-angular dir> --sizes 1000000 --queries 64 --protocol-queries 30 \
  --configs 1:1:4:4,16:4:4:4,32:8:4:4,64:8:4:4,64:16:4:4,64:16:1:4 \
  --out benchmarks/results/private_rank_protocol_1m.json

The 10^5 files use --sizes 100000, the default cluster list for the sweep, and the configs 1:1:4:4,16:8:4:4,32:8:4:4,64:8:4:4,64:16:4:4,64:16:1:4. The data directory holds train.f32 and test.f32 (little-endian f32 rows of 100).

References

  1. Henzinger, Hong, Corrigan-Gibbs, Meiklejohn, Vaikuntanathan. One Server for the Price of Two: Simple and Fast Single-Server Private Information Retrieval. USENIX Security 2023. https://eprint.iacr.org/2022/949

  2. Henzinger, Dauterman, Corrigan-Gibbs, Zeldovich. Private Web Search with Tiptoe. SOSP 2023. https://dl.acm.org/doi/10.1145/3600006.3613134 (read: https://par.nsf.gov/servlets/purl/10530535)

  3. Menon, Wu. YPIR: High-Throughput Single-Server PIR with Silent Preprocessing. USENIX Security

    1. https://www.usenix.org/system/files/usenixsecurity24-menon.pdf

  4. Alkim, Ducas, Pöppelmann, Schwabe. Post-quantum key exchange: a new hope. USENIX Security 2016, Section 6.

  5. Albrecht, Player, Scott. On the concrete hardness of Learning with Errors. J. Math. Cryptol. 2015; software: https://github.com/malb/lattice-estimator

  6. Albrecht et al. Homomorphic Encryption Security Standard, v1.1, 2018. https://homomorphicencryption.org/standard/

512 files · 481 not served here

Advantages

  • Supports local-first operation with no external service calls or telemetry. evidence: README.md
  • Provides a memory API that allows for explicit fact removal via a forget operation. evidence: README.md

Limitations

Security

Risk level: Medium risk

This brain runs

Install scripts (1)

  • benchmarks/results/sbg_positions_development/setup.sh: sh benchmarks/results/sbg_positions_development/setup.sh

MCP servers (3)

  • integrations/editors/claude-code/plugin/.mcp.json (writerslogic-warm): npx -y writerslogic-warm-mcp
  • integrations/editors/claude-desktop/claude_desktop_config.json (writerslogic-warm): npx -y writerslogic-warm-mcp
  • integrations/editors/gemini-cli/gemini-extension.json (writerslogic-warm): npx -y writerslogic-warm-mcp

Hooks (1)

  • integrations/editors/claude-code/plugin/hooks/hooks.json (SessionStart): node
  • Medium risk: runs-mcp-server-unpinned-runner (integrations/editors/claude-code/plugin/.mcp.json)
  • Medium risk: runs-mcp-server-unpinned-runner (integrations/editors/claude-desktop/claude_desktop_config.json)
  • Medium risk: runs-mcp-server-unpinned-runner (integrations/editors/gemini-cli/gemini-extension.json)
  • Low risk: scripts-present (benchmarks/results/sbg_positions_development/setup.sh)

Attribution and licence

Created by
Writerslogic
Declared authors
  • WritersLogic, Inc. (declared in package.json)
  • WritersLogic, Inc. (declared in pyproject.toml)
  • WritersLogic Contributors (declared in CITATION.cff)
Publisher
Writerslogic (Official Writerslogic project)
Source
writerslogic/warm · commit e176d55
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Writerslogic.

Install from source

481 of its files are not served here, so there is no ZIP. writerslogic/warm at e176d55