WARM

<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.

Who it's for

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

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.