AutoGineer
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/RELEASING.md

<!-- Copyright 2024-2026 WritersLogic Contributors -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

Releasing WARM

The engine and binding tags produce artefacts, provenance attestations and SBOMs. MCP launchers have their own version and release tag. Pull requests do not publish. Manual runs default to builds and checks; explicit publish inputs enable protected crate-only recovery, npm publication on main, or publication from the Python release workflows. MCP manual runs do not publish.

TagWorkflowProduces
vX.Y.Z.github/workflows/release.ymlthe crate, 8 writerslogic-warm-* native packages and root writerslogic-warm, Python wheels and sdist (as release assets), SBOMs, SLSA provenance, a draft GitHub release; then publishes the crate and native npm packages
py-models-vX.Y.Z.github/workflows/warm-models-release.ymlthe pinned default offline warm-models pack, published to PyPI through Trusted Publishing
py-vX.Y.Z.github/workflows/warm-py-release.ymlwarm-python wheels and sdist, published to PyPI through Trusted Publishing
sdk-vX.Y.Z.github/workflows/warm-sdk-release.yml and .github/workflows/warm-js-sdk-release.ymlportable warm-sdk clients: Python wheel/sdist on PyPI and JavaScript/TypeScript package on npm
mcp-vX.Y.Z.github/workflows/warm-mcp-release.ymlfive warm-mcp binaries, checksum tables embedded in npm and PyPI launchers, a GitHub release, then the launcher packages and official MCP Registry entry

Publish a new model pack before a native wheel that requires that new version through [embed]. The existing warm-models==0.1.0 pin does not require another model release for engine 0.6.8. The Python distributions have separate release tags and Trusted Publisher workflows. For a full engine release, push both vX.Y.Z and py-vX.Y.Z at the same commit; the native wheels build twice.

The npm native binding writerslogic-warm follows the engine version, currently 0.6.8. The JavaScript and Python HTTP clients share SDK version 0.2.1 and the sdk-v0.2.1 tag; their manifests are bindings/js/warm-sdk/package.json and bindings/python/warm-sdk/pyproject.toml. The engine version script does not bump the SDKs or MCP launchers. The MCP launchers use version 0.1.7 and the mcp-v0.1.7 tag. Framework adapters in integrations/js and integrations/python, and the two Claude memory-tool packages, have no publication workflow in this release pipeline. Their first publication is separate from the 0.6.8 maintenance release.

Portable HTTP SDK release

Keep both SDK manifests and their lockfiles at the shared SDK version, and document compatibility changes, including removed adapters. Run Python SDK release on the candidate with publish=false. Its gate builds with uv build, tests against a real warm-server, and checks a clean wheel install, import and py.typed marker. Require the framework contract jobs in ci.yml as well.

The JavaScript client lives in bindings/js/warm-sdk, not the repository-root npm package. Require the build-only .github/workflows/js-sdk.yml checks before .github/workflows/warm-js-sdk-release.yml publishes: type checking, client tests, clean packed CommonJS/ESM consumers, a real server memory round trip, and absence of native/runtime dependencies. Importing the client must not load the embedded engine. Keep provenance, registry signature verification and the published-consumer check in the release gate.

Publish one signed sdk-vX.Y.Z tag matching both clients. It triggers their separate registry workflows. Do not reuse an existing version, substitute the engine version, or mark the shared SDK release available until both registry installs have been verified.

MCP launcher release

writerslogic-warm-mcp on npm and warm-mcp on PyPI is versioned separately from the engine. Its launchers download warm-mcp from a mcp-vX.Y.Z GitHub release and verify its hash against a table inside the package. The release workflow builds macOS arm64 and x64, Linux arm64 and x64 (glibc 2.17 minimum), and Windows x64 binaries. It rejects missing or extra assets, tests both launchers with a local asset server, packs and installs both distributions, creates the GitHub release, then publishes to npm, PyPI and the official MCP Registry. The Registry entry uses both packages, and the package metadata proves ownership of io.github.writerslogic/warm-mcp.

Before the first release, add a pending Trusted Publisher for the new project at https://pypi.org/manage/account/publishing/: project warm-mcp, owner writerslogic, repository warm, workflow warm-mcp-release.yml, environment pypi. PyPI creates the project on the first successful upload. The repository's NPM_TOKEN secret must have publish access to writerslogic-warm-mcp.

To check the pipeline without publishing, run MCP launcher release with workflow_dispatch or open a pull request touching its files. To publish, tag the commit containing the tested workflow with mcp-vX.Y.Z where X.Y.Z matches integrations/mcp/npm/package.json, integrations/mcp/pypi/pyproject.toml, the Python launcher's __version__, and integrations/mcp/server.json (including both package entries), and push the signed tag. python3 scripts/ci/mcp-release.py mcp-vX.Y.Z checks those versions and registry metadata. A changed warm-mcp binary needs a new launcher release even when launcher source is unchanged. The workflow never replaces an existing release or registry version. If one publish job fails after the GitHub release exists, correct its credentials or publisher configuration and rerun that job only.

After the official Registry entry is active, submit the repository through Glama's Add MCP Server form. glama.json names the maintainer, as in scrivener-mcp. Verify third-party directories separately; an official Registry entry does not confirm their listings. At the 0.1.2 release, mcp.so has a free submission path and an optional $39 paid publication option. Use the free path; do not pay. PulseMCP is not accepting submissions. The modelcontextprotocol/servers repository now contains reference servers and directs community server discovery to the official Registry.

After Glama approves the listing, a signed-in maintainer must configure its Docker release. That form generates a Dockerfile from its fields; the repository-root Dockerfile is built and tested separately by mcp-container.yml. Clear the Pinned Commit SHA (5250df9 points to a commit before the repository Dockerfile and current tool definitions); leave it empty so Glama can sync newer commits. Pinning a SHA requires updating it for every subsequent release.

Set Base Image to debian:trixie-slim and Node.js version to 24. Glama installs Node and mcp-proxy in its generated image. Enter this Build Step after publishing the MCP launcher to npm:

npm install -g --no-audit --no-fund writerslogic-warm-mcp@latest && WARM_MCP_CACHE_DIR=/tmp/warm-mcp-cache writerslogic-warm-mcp --version && install -m 755 /tmp/warm-mcp-cache/*/*/warm-mcp /usr/local/bin/warm-mcp && install -d -m 1777 /data

The npm launcher verifies its downloaded binary against the checksum embedded in that release; the build copies the verified binary into the image so it needs no download at runtime. Set CMD Arguments to ["mcp-proxy","--","/usr/local/bin/warm-mcp","--data-dir","/data"], Environment Variables JSON Schema to {"type":"object","properties":{}}, and Placeholder Parameters to {}. Persistent memory on a hosted deployment requires Glama's optional /data volume.

Click Deploy; after its build test succeeds, choose Make Release and publish the MCP launcher version. The build step picks up npm's latest published launcher on each build. Glama requires a new build test and release publication for each version. A release enables hosted deployment and security scans; a GitHub tag alone does not.

Then check the server score and confirm it can deploy and introspect all eight tools. Review every tool's six Tool Definition Quality Score dimensions, the server coherence score, and the listed security and maintenance findings. Use Glama's specific findings to improve any dimension below 5/5, any overall score below the highest tier, or any reported risk; then confirm the next scan reflects the fix. The mcp-container.yml CI check covers the Docker build and stdio introspection before submission.

Afterward, confirm npm view writerslogic-warm-mcp version and the PyPI project page show X.Y.Z. Run uvx warm-mcp --version and npx -y writerslogic-warm-mcp --version on a supported platform with an empty launcher cache; these commands print the underlying engine's version, which is independent of the launcher version.

What is built

  • Python (python-wheels.yml): abi3 (cp39-abi3) wheels for manylinux2014 x86_64 and aarch64, musllinux_1_2 x86_64 and aarch64, macOS arm64 and x86_64, Windows x64, and the sdist. Each wheel is installed into an empty virtualenv with no source tree and no network, then a real associative search and a resonator factorization run through it (scripts/ci/smoke_python.py). Linux wheels are additionally installed in a Debian 11 (glibc 2.31, Python 3.9) or Alpine container.

  • Embedded npm (npm-packages.yml): writerslogic-warm-{darwin-arm64, darwin-x64, linux-arm64-gnu, linux-arm64-musl, linux-x64-gnu, linux-x64-musl, win32-arm64-msvc, win32-x64-msvc} plus the JavaScript-only loader package writerslogic-warm, whose optionalDependencies select the binding by os, cpu and libc. glibc bindings are linked against glibc 2.17, musl bindings with zig. The tarballs are installed into an empty project on a machine of every target (Alpine containers for musl, Debian 11 for glibc) with the root's optional dependencies pointed at the local tarballs, so npm itself must pick exactly one package, and a document search must succeed (scripts/ci/smoke-node.cjs). The root package.json (napi.targets) is the single list of platforms and scripts/ci/npm-platform-packages.cjs refuses to pack if it disagrees with optionalDependencies or any binding is missing.

  • Portable npm client (js-sdk.yml): warm-sdk from bindings/js/warm-sdk, with CommonJS, ESM and TypeScript declarations. It has no platform packages or native dependency; its server runs separately. Publication uses the SDK tag and warm-js-sdk-release.yml.

  • Crate: cargo package --locked, which also builds the packaged tarball.

  • SBOM: a CycloneDX 1.5 JSON per artefact (cargo-cyclonedx, npm sbom), named <artefact>.cdx.json and paired by scripts/ci/pair-sboms.py, which refuses a release where any artefact lacks one.

  • Provenance: actions/attest-build-provenance signs a SLSA provenance statement for every artefact and SBOM, and actions/attest-sbom binds each SBOM to its artefact. The bundle is also a release asset (provenance.intoto.jsonl).

One-time setup (repository settings, by the maintainer)

These cannot be committed; the publish jobs wait on them.

  1. Environments (Settings, Environments), each with required reviewers: release, crates-io, npm, pypi.

  2. crates.io: add this repository's release.yml and environment crates-io as a Trusted Publisher for warm-rust. The job uses rust-lang/crates-io-auth-action and holds no token.

  3. npm: configure publishing authority for writerslogic-warm, its eight writerslogic-warm-* platform names, and the separate portable warm-sdk package through NPM_TOKEN (a repository or npm environment secret). Publishing uses --provenance. Legacy package retirement runs separately through retire-legacy-npm.yml; registry policy and interactive two-factor authentication can restrict permanent deletion.

  4. PyPI: add pending Trusted Publishers under owner writerslogic, repository warm, environment pypi: warm-models uses warm-models-release.yml, warm-python uses warm-py-release.yml, and warm-sdk uses warm-sdk-release.yml. The MCP launcher uses warm-mcp-release.yml with the same owner, repository and environment. PyPI permits three pending projects at a time; publish one before registering the fourth.

Cut a release

  1. Version. uv run python scripts/ci/bump-version.py X.Y.Z sets Cargo.toml, Cargo.lock, package.json with its optionalDependencies, package-lock.json and docs/server/openapi.json; scripts/ci/check-versions.py runs in every artefact job and again against the tag, so a mismatch fails the build.

  2. Changelog. Use git-cliff 2.14.2, matching the pinned workflow; older versions can assign merged branch commits to releases that never contained them. Run git cliff -c cliff.toml --tag vX.Y.Z -o CHANGELOG.md and commit as chore: Update changelog. The tag argument prepares the release heading without creating a Git tag. Generate it on the intended UTC tag date and require the changelog gate on the actual tag. Tag the commit before any [skip ci] commit (those run no workflows).

  3. Dry run. Merge to main, then run Actions, Release and Python native release on main. Keep all publish inputs false. Run both SDK build/check workflows and MCP launcher release when those distributions change; run Python models release only when a new pack is needed. The dry runs build and test without publishing. The Reproducible build workflow must also be green on that commit.

  4. Tag and push (signed): git tag -s vX.Y.Z -m vX.Y.Z && git push --no-follow-tags origin refs/tags/vX.Y.Z, and the same for py-vX.Y.Z. Publish py-models-vX.Y.Z first if the native [embed] extra needs a new model pack. Publish matching independent sdk-vX.Y.Z and mcp-vX.Y.Z tags when those distributions change. Use --no-follow-tags on every branch and tag push, naming only the intended refs. Approve the release, crates-io, npm and pypi environments when asked.

  5. GitHub release. release.yml leaves a draft release holding every artefact, SBOM, SHA256SUMS and the provenance bundle. Prepare the notes, but keep it a draft until the registry and artefact checks below pass, then publish it. The data releases (evidence-v*) use other tags and never trigger these workflows.

  6. Native npm listing. Verify the root package and all eight platform packages are available:

    version=X.Y.Z
for package in writerslogic-warm \
  writerslogic-warm-darwin-arm64 writerslogic-warm-darwin-x64 \
  writerslogic-warm-linux-arm64-gnu writerslogic-warm-linux-arm64-musl \
  writerslogic-warm-linux-x64-gnu writerslogic-warm-linux-x64-musl \
  writerslogic-warm-win32-arm64-msvc writerslogic-warm-win32-x64-msvc; do
  test "$(npm view "${package}@${version}" version)" = "$version" || exit 1
done
npm view "writerslogic-warm@${version}" deprecated # must print nothing
npm dist-tag ls writerslogic-warm                  # latest must be X.Y.Z

    Confirm the latest registry page shows no deprecation banner, the README logo renders, and npm install writerslogic-warm resolves to X.Y.Z. npm can acknowledge a new package before its version is available; a 0.0.0-stage placeholder alone is not a published binding. Require the verify-published job to pass for this release: it waits for the root and every declared optional platform package with a fresh npm cache, installs the published root package in a clean consumer, verifies npm signatures, and runs a document search. Registry metadata or a successful tarball build alone does not establish that consumers can use the release.

  7. Verify what was shipped (see below).

<a id="first-npm-release-under-warm-sdk"></a>

JavaScript package availability

The JavaScript packages are portable warm-sdk 0.2.1 and embedded writerslogic-warm 0.6.8. Check available npm versions for the client and the embedded engine before choosing a registry release. The installation guide also covers source builds. The existing native writerslogic-warm family is retained; it is not deprecated or replaced by the client.

For the SDK, verify npm view [email protected] version, install that exact version in a clean consumer, verify signatures, and run an authenticated memory round trip against the supported server. Verify the Python client independently under the same SDK tag. Keep native platform build/install gates, provenance and registry consumer checks for the embedded package.

The 0.6.6 release partially published the new npm names: seven platform packages succeeded, but npm rejected warm-sdk-win32-x64-msvc for package-name spam detection and the job stopped before publishing root warm-sdk (failed job). That historical failure does not block either current package: the embedded release uses the existing writerslogic-warm-* names, and the portable client has no native helpers. Do not retry or require clearance of warm-sdk-win32-x64-msvc for these releases. Preserve the historical tags and receipts.

Existing embedded consumers retain writerslogic-warm imports, including /semantic, /memory and /vectra, and their existing store directories and configuration. Adopting the portable WarmClient requires an HTTP server and an explicit API migration; it is not a rename of WarmMemorySystem. There is no warm-sdk/embedded export.

The framework adapters in integrations/js remain explicit native integrations with a writerslogic-warm >=0.6.5 peer. Their separate publication is not part of the SDK or engine release. MCP, embedding-model packages, WebAssembly and Rust keep their existing identities.

Verify an artefact

gh attestation verify warm_python-X.Y.Z-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \
  --repo writerslogic/warm
gh attestation verify writerslogic-warm-linux-x64-gnu-X.Y.Z.tgz --repo writerslogic/warm
npm audit signatures            # in a clean consumer of the package being released
sha256sum -c SHA256SUMS         # next to the downloaded release assets

Reproducible builds

.github/workflows/reproducible.yml builds warm-eval, warm-server, the napi cdylib, the Python wheel and the crate on two independent runners from different checkout paths and fails unless the SHA-256 of every artefact is identical (scripts/ci/repro-build.sh, scripts/ci/compare-hashes.py). Inputs that are pinned: the committed Cargo.lock (--locked), SOURCE_DATE_EPOCH (the commit time), maturin, no incremental compilation, and --remap-path-prefix for the checkout, cargo home and rustup home. The Rust toolchain is the runner's current stable, so both legs must run in the same workflow run.

Result of the first runs (two runners, different checkout directories): warm-eval, warm-server, the napi cdylib and the crate are bit-for-bit identical. The Python wheel is identical member for member except *.dist-info/sboms/* (and RECORD, which lists its hash), the SBOM maturin embeds, whose bom-refs contain the absolute checkout directory; the workflow therefore allows the wheel hash to differ and fails if any other member differs.

ArtefactReproducibleReason
warm-eval, warm-server, napi cdylib, .crateyes
Python wheel (manylinux x86_64, built natively)all members except the embedded SBOMabsolute checkout path in the SBOM bom-refs

Not covered: the per-platform npm bindings and the cross-compiled wheels, which depend on the zig and napi cross toolchains downloaded at build time (their SHA-256 are in SHA256SUMS and the attestations, not compared).

If something goes wrong

  • A publish job failed partway: inspect its logs and the workflow at that tag before retrying. Current npm release steps skip existing versions, cargo publish refuses an existing version, and PyPI uses skip-existing. Historical tag workflows may lack current recovery guards; a re-run uses the workflow file at the tag. Fixes on main apply from the next tag, not to the old run.

  • npm answered E403 Package name triggered spam detection for a new package name: ask npm support to clear that exact name and verify the resolution before another publish. For 0.6.6, the rejected name was warm-sdk-win32-x64-msvc; seven platform packages had succeeded and the root was not published. This error does not establish a credential or ownership failure, and changing the version alone does not clear it. The current native family uses writerslogic-warm-*; clearance of the abandoned helper name is not a release prerequisite. Preserve the signed 0.6.6 tags and the existing v0.6.7, py-v0.6.7, sdk-v0.2.0 and mcp-v0.1.6 tags when preparing the new releases. Do not move or reuse them.

  • For npm-only recovery from the reviewed candidate on main, run gh workflow run npm-packages.yml --ref main -f publish_npm=true after resolving the failure. This protected path builds and verifies the packages, compares the integrity of any existing versions before skipping them, and requires the published-package consumer gate. Confirm the candidate's version and commit first; the normal full release uses the signed engine tag.

  • A tag's crate upload failed because the archive is too large: fix the Cargo.toml package contents on main and verify cargo package --locked --no-default-features reports less than 9.5 MB compressed. The crates-io environment normally permits only v* tags; temporarily add main as an allowed deployment branch while retaining the v* policy and required reviewer. Run Release on main with publish_crate_only=true and approve the crates-io environment. Remove the temporary main policy after the job finishes. This protected run packages, attests, and publishes only the crate. Verify that the crate index checksum matches the crate-recovery artifact and the registry download. If the GitHub release is still a draft, replace its crate, crate SBOM, and matching SHA256SUMS entries before publishing. If it is already immutable, leave those assets intact; record the recovery commit, registry checksum, and attestation in the editable release notes so readers can distinguish the published crate from the original oversized release asset. Never move the signed release tag.

  • Published a bad version: crates.io cargo yank --version X.Y.Z; npm npm deprecate <affected-package>@X.Y.Z "reason" (unpublish only within 72 hours); PyPI yank in the web UI (no API). Then release X.Y.(Z+1); never re-tag.

  • A signed release tag pushed by mistake: cancel its workflows and leave the tag unchanged. Keep any draft unpublished and prepare a new version before approving publication.

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