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/PUBLIC-BENCHMARKS.md

Public benchmarks

Measured 2026-10-05 on an Apple M4 (10 cores, macOS). Results: benchmarks/results/public_*.json. Harness: benchmarks/public/prepare.py (downloads and embeds data outside the repository), src/bin/research/public-bench.rs (drives WARM) and benchmarks/public/evaluate.py (scores runs and runs the comparison libraries on the same data).

The machine was not idle: load average ranged from 4 to 37 during the runs, and every result file records it. Recall and nDCG are unaffected by load. Latency and queries/second are indicative; the gaps reported below are far larger than the load effect.

Text retrieval (BEIR)

BEIR test splits, scored with pytrec_eval. Embeddings: sentence-transformers/all-MiniLM-L6-v2 at revision 1110a243fdf4706b3f48f1d95db1a4f5529b4d41, L2-normalized, computed by prepare.py.

MethodSciFact nDCG@10SciFact R@100NFCorpus nDCG@10NFCorpus R@100
WARM hybrid (document API, stemmed BM25 + exact cosine, min-max score blend)0.7290.9530.3550.322
WARM lexical (document API BM25, Porter stemming)0.6880.9250.3230.249
WARM dense (document API, exact cosine)0.6450.9250.3170.311
WARM sparse vector path (from_dense + inverted index, D=16384)0.4700.7790.2090.207
Reference: exact cosine in NumPy, same embeddings0.6450.9250.3160.312
Reference: BM25 as published in the BEIR paper (Thakur et al. 2021, main nDCG@10 results)0.6650.325
Previous WARM hybrid (unstemmed BM25, reciprocal rank fusion; measured 2026-10-05)0.6830.9540.3440.325
Previous WARM lexical (unstemmed)0.6620.8860.3070.237

Re-measured 2026-10-07 (load 70 to 119, which does not affect nDCG) after two document-API changes chosen on NFCorpus dev and SciFact train qrels only (benchmarks/results/proxies_2026-10_beir.json; the test qrels were read once, for this table): Porter (Snowball English) stemming of BM25 terms (+0.024 / +0.032 on dev/train; +0.026 / +0.016 on test) and a min-max score blend of the lexical and semantic lists in place of reciprocal rank fusion (+0.017 / +0.016 on dev/train; RRF remains available as fusion: "rrf"). Chunks stored before stemming keep matching unstemmed query terms.

  • WARM's dense search matches the independent NumPy reference. This is a correctness check of the document API; it says nothing new about the embedding model.

  • WARM's BM25 is now above the published BM25 on SciFact (+0.023) and 0.002 under it on NFCorpus.

  • Hybrid search is the best configuration on both sets: +0.084 / +0.038 nDCG@10 over dense alone.

  • The sparse vector path loses about 27% (SciFact) and 34% (NFCorpus) of nDCG@10 relative to exact cosine on the same embeddings. It is not suitable as the primary semantic retrieval path; the document API is.

Vector search (ann-benchmarks)

Datasets and ground truth from ann-benchmarks: nytimes-256-angular (290,000 train, 10,000 queries) and glove-100-angular (1,183,514 train, 10,000 queries). Every system searches single-threaded, one query at a time; builds use all cores. FAISS 1.15.1, hnswlib 0.8.0.

This table measures WARM's sparse vector path, not the graph index (see COMPARISON): each dense vector is encoded with from_dense (D=16384, 64 active indices) and searched exactly in the inverted index. Its query time includes encoding, because the other systems take dense input directly.

Systemnytimes recall@10nytimes QPSglove recall@10glove QPSglove memory
WARM sparse (D=16384)0.342040.25342.5 GB RSS
FAISS flat (exact)0.992061.001240.47 GB vectors
FAISS HNSW M=16, efSearch=160.6913,7820.5619,8610.64 GB
FAISS HNSW M=16, efSearch=1280.882,8750.834,1110.64 GB
FAISS HNSW M=32, efSearch=5120.965090.966820.80 GB
hnswlib M=16, ef=1280.881,2020.833,3680.63 GB (estimate)

Full sweeps are in the result files.

  • WARM is behind at every operating point. On glove, HNSW reaches higher recall than WARM at roughly 600 times the throughput, and exact FAISS search is faster than WARM while returning the right answer.

  • The cause is the encoder, not the index: the inverted index is exact over the sparse codes, but the codes keep only part of the neighbour structure. The true top-10 is inside WARM's top-100 for 54% of results on both sets (experimental_prefilter in the result files), so even an exact re-rank of 100 candidates would not close the gap.

  • Encoding dominates build time (155 s for nytimes, 265 s for glove, all cores) and is about half of query time on nytimes.

Quantized graph index (core::qgraph) vs the field

VGraph (core::qgraph::vertex) is a Vamana-style graph (out-degree 64 on nytimes, 32 on glove, build_ef 200, alpha 1.0, HNSW-like upper layers for the entry point) with one 8-bit LVQ code per vertex for the traversal and an 8-bit residual code for the re-rank of the best rerank pool candidates (public-bench ann-qgraph --index vertex --residual). An opt-in 4-bit traversal encoding (--vertex-bits 4 --residual-bits 8 --align-rows --reorder --id-bytes 3) costs no recall and saves 24% of the bytes on nytimes and 16.5% on glove. Parameters were chosen on held-out train vectors (--holdout 2000; the test queries are never read for a decision). benchmarks/results/qgraph_merge_verification_heldout.json (2026-10-07, one clean paired run per dataset, 11 rounds under one lock) keeps the current search path (x1.30 / x1.38 over the previous code at recall 0.90 / 0.95 on nytimes, x1.48 / x1.58 on glove, 11 of 11 rounds) and keeps the 8-bit encoding as the default: the 4-bit encoding wins x1.20 / x1.18 on nytimes but only x1.01 / x0.97 on glove (6 and 3 of 11 rounds), so it is a memory-only gain.

nytimes-256-angular, test set, Apple M4 (NEON)

benchmarks/results/public_qgraph_nytimes-256-angular.json (commit d985308, 2026-10-07): 10,000 test queries, every system single-threaded one query at a time, 3 repeats (median QPS, the runs are in the file), QPS at a target interpolated in log(QPS) between the Pareto-frontier points that bracket it; builds use all cores; competitors at the parameters their authors recommend (benchmarks/public/ann_extra.py). Every row ran with the 1-minute load above the gate of 3 (other builds and timings shared the machine; load 5 to 103, recorded per row), so the absolute QPS are indicative only, and the two WARM rows ran at different loads (9-28 against 7-9). Table: uv run --script benchmarks/public/qgraph_table.py nytimes-256-angular.

SystemQPS @ 0.90QPS @ 0.95WARM/sys @ 0.90Index bytessys/WARM bytesBuild sLoad 1m
WARM VGraph (8-bit codes, rerank)4,409not reached1.00226,310,9601.00111 (graph from the checked cache: 1)9-28
WARM VGraph (4-bit codes, opt-in)13,133not reached0.34171,790,9600.76(cache: 4)7-9
SymphonyQG (rabitqlib, raw refinement)5,913not reached0.75705,280,1663.12176-8
SymphonyQG (rabitqlib, 4-bit refinement)not reachednot reached447,761,2101.98189-13
FAISS HNSW M=162,0383792.16338,802,5541.505111-75
FAISS HNSW M=322,0115092.19375,882,6581.66935-64
hnswlib M=161,3523483.26336,400,0001.49517-37
RaBitQ HNSW 1+42,066not reached2.1395,277,7810.422911-28
RaBitQ IVF 1+89698034.5592,637,2820.411515-29
RaBitQ IVF 1+4940not reached4.6955,517,2820.251233-63
Lucene HNSW M=161,1082783.98406,592,0561.802436-46
Lucene HNSW M=3235812912.32466,298,8402.0685142-103

Read as the file reads it:

  • At recall 0.90 the 8-bit VGraph is 2.2x FAISS HNSW (M 16 and 32), 3.3x hnswlib, 2.1x RaBitQ HNSW, 4.6x RaBitQ IVF and 4.0x Lucene HNSW on QPS at 0.60-0.67x of their bytes. It LOSES to SymphonyQG (the authors' library, raw-vector refinement) by 0.75x on QPS while using 0.32x of its bytes. The 4-bit VGraph row is 2.2x SymphonyQG, but it ran at load 7-9 while the 8-bit row ran at 9-28; the paired held-out ratio of 4-bit over 8-bit is x1.20, not x3. Treat the 4-bit row as unconfirmed until a rerun at equal load.

  • At recall 0.95 no WARM row is bracketed: both sweeps stopped at ef 512 with recall 0.948 (the test set is harder than the held-out train vectors, where ef 384 gave 0.950). FAISS, hnswlib, Lucene and RaBitQ IVF 1+8 reach it (379, 509, 348, 129-278 and 803 QPS).

  • Memory: RaBitQ IVF (1+4: 55.5 MB, 1+8: 92.6 MB) and RaBitQ HNSW (95.3 MB) are 2.4-4.1x SMALLER than the 8-bit VGraph (226 MB) and 1.8-3.1x smaller than the 4-bit one (172 MB). That is a loss on index bytes at equal recall.

  • Build time: FAISS 51-93 s, SymphonyQG 17 s, RaBitQ 12-29 s, Lucene 243-851 s, VGraph 111 s for the full nytimes graph (measured once at load 47 while building the checked cache; the paired build numbers are in qgraph_vertex_build_heldout.json). Build time is the one metric where losing is accepted; it is still a loss against SymphonyQG and RaBitQ here.

  • Not run on this machine: NGT (its quantized graph needs the qbg command, which the macOS Homebrew build lacks; the ONNG stand-in did not build within its 30-minute cap), Glass, DiskANN and ScaNN (x86-only builds). They need an x86 machine.

  • glove-100-angular was not run in this pass.

The earlier edge-code index (1,024-bit RaBitQ codes per edge, 2.97 GB on nytimes, 7,297 / 1,427 QPS at load below 3) is superseded by VGraph; its sweeps stay in benchmarks/results/public_qgraph_edge_<set>.json. The competitors are timed through a Python per-query loop (Lucene through a Java loop) and WARM through a native loop; that per-query overhead was not measured.

Stop rule and 1-bit screen (held-out, 2026-10-07)

benchmarks/results/qgraph_stop_screen_heldout.json (held-out train vectors, test set unread). VSearchParams::patience ends a search after that many expansions without a change to the 10 best estimates: 17-29% fewer estimates at equal recall on both sets, and in paired rounds (load 11-185, gate unmet, ratios only) x1.33 (4 of 5 rounds) on nytimes and x1.42 (4 of 4) on glove at recall 0.95, neutral at 0.90; off by default, --patience in the bench. The opt-in 1-bit screen before the 8-bit estimate skips 76% of the estimates on nytimes at equal recall but is slower in nearly every round (x0.65-0.87): its scalar popcount costs as much as the SDOT estimate; recorded as a negative result, off by default.

Agent long-term memory (LongMemEval_S)

Retrieval only, no LLM. Data: LongMemEval_S from the xiaowu0162/longmemeval-cleaned release (revision 98d7416c24c778c2fee6e6f3006e7a073259d48f, longmemeval_s_cleaned.json, sha256 d6f21ea9d60a0d56f34a05b609c79c88a451d2ae03597821ea3d5a9678c3a442), the release the LongMemEval repository now points to (September 2025 clean-up of the history sessions); the paper's numbers predate it. Embeddings: the same all-MiniLM-L6-v2 revision as above, L2-normalized. Metrics come from the repository's own src/retrieval/eval_utils.py (commit 9e0b455f, hash recorded in the result file), applied the way run_retrieval.py and print_retrieval_metrics.py do: items are user turns only, a session is the concatenation of its user turns, and the 30 abstention questions plus questions with no answer-bearing user turn are excluded, leaving 419 of 500 questions (only 5 of the 56 single-session-assistant questions remain, so that row is not informative). Each question is searched in a fresh store holding only its own haystack (about 48 sessions, 245 user turns). Recall is recall_all (every evidence item in the top k) and nDCG is ndcg_any, the two figures the official script prints; recall_any is in the result file. "Round" is the official user-turn granularity. Turn-level rows score the round run against the labelled turns; session-level rows of a round run use the official turn-to-session conversion. Results: benchmarks/results/public_longmemeval_s.json.

GranularityLevelMethodRecall@5Recall@10nDCG@5nDCG@10
RoundTurnWARM dense (exact cosine)0.5110.7110.5700.623
RoundTurnWARM lexical (BM25)0.5990.7180.6420.675
RoundTurnWARM hybrid0.6680.7850.6810.712
RoundSessionWARM dense (exact cosine)0.6900.8400.6110.647
RoundSessionWARM lexical (BM25)0.6680.7680.6580.684
RoundSessionWARM hybrid0.7640.8540.7020.723
SessionSessionWARM dense (exact cosine)0.8520.9380.8610.878
SessionSessionWARM lexical (BM25)0.8230.8930.8620.877
SessionSessionWARM hybrid0.8760.9520.9040.919

WARM dense reproduces an independent NumPy exact-cosine ranking on the same embeddings to every digit (the result file carries both).

On this data and model, hybrid is above dense on every overall metric at every granularity and level (nDCG@10: +0.089 round/turn, +0.076 round/session, +0.041 session). The runs are single deterministic passes with no confidence intervals or significance test. Caveats that bound the comparison: MiniLM truncates input at 256 tokens, so a session embedding sees only the start of the concatenated user turns (the lexical index sees all of it); WARM BM25 is the engine's own, not the rank_bm25 used by the official flat-bm25; zero-score items follow scored items in haystack order in the lexical run.

Recall@10 and nDCG@10 per question type (recall_all / ndcg_any):

TypenSession run, sessionRound run, session (dense)Round run, session (hybrid)Round run, turn (dense)Round run, turn (hybrid)
multi-session1210.909 / 0.8950.736 / 0.5850.727 / 0.6540.545 / 0.5530.595 / 0.633
temporal-reasoning1270.953 / 0.8930.756 / 0.5700.850 / 0.6900.614 / 0.5380.787 / 0.678
knowledge-update721.000 / 0.9820.986 / 0.6860.986 / 0.7720.903 / 0.6730.986 / 0.772
single-session-preference300.900 / 0.7880.967 / 0.7030.800 / 0.5430.767 / 0.6780.633 / 0.522
single-session-user641.000 / 1.0000.969 / 0.8270.969 / 0.9360.953 / 0.8220.969 / 0.936
single-session-assistant51.000 / 1.0001.000 / 0.9001.000 / 0.8771.000 / 0.9001.000 / 0.877

The session-run column is hybrid. The weakest types are multi-session (evidence spread over several sessions, all of which must be retrieved), single-session-preference, and temporal-reasoning. Preference is the one type where hybrid is below dense at round granularity (30 questions; lexical matching works against implicit preference questions). Temporal questions are where round-level hybrid helps most (turn Recall@10 0.614 to 0.787), but they are still weaker than the other types, and WARM has no date-aware filtering that would use the question date.

Published numbers (Wu et al., ICLR 2025, Table 3), LongMemEval_M with Stella V5 1.5B:

Value / keyRecall@5NDCG@5Recall@10NDCG@10
Round, K = V0.5820.4810.6920.512
Round, K = V + LLM-extracted facts0.6440.4980.7840.536
Session, K = V0.7060.6170.7830.638
Session, K = V + LLM-extracted facts0.7320.6200.8620.652

These are not comparable with the table above: M has about 500 sessions per history against about 48 in S, the embedding model is a 1.5B-parameter model against a 22M-parameter one, the dataset release differs, and the paper's recall variant and level mapping were not re-derived here. No ranking against the paper is implied.

What this means

  • For semantic search over text, use the document API: exact cosine reproduces the embedding model's quality, and hybrid search with the built-in BM25 improves on it.

  • Do not use the sparse vector path (memorize_vector / query_vector) where nearest-neighbour recall matters. Improving it needs a different encoder; making the current one faster does not.

  • As a vector index, VGraph is ahead of FAISS HNSW, hnswlib and Lucene HNSW on single-thread QPS at recall 0.90 and below them on bytes on nytimes (Apple M4, load above the gate: indicative), and behind SymphonyQG on QPS and behind RaBitQ on bytes. No x86 number exists yet, and the distinctive parts of WARM (the compositional VSA algebra, structured memory and provenance) are not what these benchmarks measure.

Reproduce

uv run --script benchmarks/public/prepare.py beir scifact
uv run --script benchmarks/public/prepare.py ann glove-100-angular
cargo build --release --features cli,mimalloc --bin public-bench
./target/release/public-bench beir --data ~/.cache/warm-bench/scifact --dim 16384 --out scifact.json
uv run --script benchmarks/public/evaluate.py beir scifact scifact.json
./target/release/public-bench ann --data ~/.cache/warm-bench/glove-100-angular --dim 16384 --out glove.json
uv run --script benchmarks/public/evaluate.py ann glove-100-angular glove.json
uv run --script benchmarks/public/prepare.py longmemeval s
./target/release/public-bench longmemeval --data ~/.cache/warm-bench/longmemeval_s --out lme.json
uv run --script benchmarks/public/evaluate.py longmemeval s lme.json

On-device model stages (local-models), Apple M4, 32 GB

Measured 2026-10-05 with public-bench lme-model --stage device (Metal; encoders f32, LLM bf16; Qwen3-Embedding-0.6B, Qwen3-Reranker-0.6B, Qwen3-4B-Instruct-2507 at the pinned revisions), every stage on, through the document API. The first 10 LongMemEval_S sessions (mean 127 user words) were ingested one session per document; 10 questions were searched with k = 10. Small sample: these are data points, not a distribution.

MeasureValue
Model load (all three)25.6 s
Ingest per session (fact extraction + embedding)mean 13.8 s, median 1.5 s, max 48.7 s
Query (LLM rewrite + 2 query embeddings + hybrid search + re-rank of 20)mean 10.3 s, median 10.6 s, max 12.8 s
Peak memory footprint (/usr/bin/time -l)17.5 GB (max RSS 9.9 GB)

Ingest time is dominated by the LLM's output length (sessions with many facts take tens of seconds); query latency by the rewrite generation. The CPU path was checked for correctness, not timed end to end. Embedder and re-ranker parity with the Python stages on 48 turns / 16 questions / 48 pairs: cosine >= 0.9999997, p(yes) max |diff| 8.4e-8 (CPU) and 7.4e-8 (Metal).

Batched model stages on Metal

benchmarks/results/local_models_batching.json. WARM now vendors the Qwen3 forward pass so that Metal and CUDA can batch: the decoder runs continuous batching with left-padded rows, the encoders run right-padded batches. Inputs: the first 64 distinct LongMemEval_S haystack sessions (prompts::fact_prompt, greedy, up to 1536 new tokens), 96 user turns, 96 questions and 96 (question, turn) pairs. Timing is paired (arms alternating, 2 rounds, 1-minute load average below 8 before every run). Throughput excludes model load.

StageBatch 1Best batchParity vs batch 1
Fact extraction, 16 sessions0.074 sessions/s, 9.6 tokens/s, peak 8.9 GBbatch 8: 0.146 sessions/s, 18.1 tokens/s, peak 13.7 GB56 / 64 outputs identical; the other 8 parse to different fact lists (205 vs 202 facts; one session went from 3 facts to none)
Embedding, 96 turns22.1 turns/sbatch 4: 27.1 turns/s (30.2 in the default-arm run)min cosine 1 - 5.4e-12, max abs diff 3.6e-7
Re-ranking, 96 pairs9.1 pairs/sbatch 1 (batch 2: 8.8, 4: 8.7, 8: 8.0)batch 16: max p(yes) diff 3.6e-7

On the full 64 sessions, untimed: batch 1 took 829 s (7,851 tokens) and batch 8 434 s (7,812 tokens), peak memory footprint 9.6 GB and 19.2 GB.

Defaults on Metal and CUDA: the decoder stays at batch 1 because batch 8 changed 12.5% of fact outputs, which is above the 5% bar for making it the default; set --batch (or Generator::set_batch) to trade that for about 2x throughput. The embedder defaults to batch 4 and the re-ranker to batch 1. CUDA was not built or run for this measurement, so the CUDA defaults remain unverified with batching.

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