Holographic Memory MCP
Summary: This MCP server gives an agent a persistent local memory store — it can write durable facts, retrieve them by meaning or filter, list/browse them, delete them, export them, and inspect the store.
remember — store a durable fact, decision, or preference with optional
id,title,tags, andmetadata; supports concurrency-safe writes viaif_versionorcreate_only, andallow_emptyfor file-like content. Marked destructive (may replace an existing id).recall — retrieve full ranked memories for a natural-language query (
k,tags,min_score); lexical by default, semantic when a model is configured. Read-only.search — find memories with exact-match metadata
filter,tags, and ranking controls (fusionblend/rrf,lexical_weight,semantic_weight,min_score); returns previews plus score details. Read-only.get — read one known memory id in full, including tags, metadata, and version; unknown ids error. Read-only.
forget — delete memories by exact
id, a list ofids(up to 1000), or an idprefix(requiresconfirm: true); returns the deletion count and any missing ids.list — browse memories in id order, filtered by
prefixortag, paginated withcursor, as previews or full text (full). Read-only.stats — inspect memory counts, embedding count, recall mode, encryption-at-rest status, store path/size, dimensions, active limits, and server version without reading contents. Read-only.
export — produce a portable snapshot of memories as
json,jsonl, ormarkdown, filtered bytag/prefix, paginated and byte-capped. Read-only.Overall: fully local (no open-world access), with read-only tools for retrieval/inspection and mutating tools for writing and deleting.
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.
Website · Docs · Get started · Standards and provenance · Evaluation · Capabilities · Limits · Contribute
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: the offline job in ci.yml runs the default-feature test suite in a network namespace without external interfaces and checks that the default dependency tree has no HTTP, TLS or socket client. HTTP clients connect to the
server you configure; model stages are opt-in.
Capability | What you get |
Document search | Chunking, stemmed BM25 over blocked postings, Boolean and phrase queries, hybrid fusion with embeddings you supply, metadata filters, byte offsets |
Vector index | Graph index with a memory-mapped vertex file, an updatable delta for inserts and deletes, optional query-aware routing trained on sample queries |
Memory API |
|
Storage | Atomic replace and delete, crash-safe journal and checkpoints, verified compaction, one writer per store |
Security | Optional AES-256-GCM storage encryption with documented coverage and limits, signed audit log, COSE/SCITT provenance |
Vector-symbolic layer | Sparse hypervectors with bind, bundle and permute, triples with multi-hop queries, Hopfield cleanup |
Related MCP server: mnemo-mcp
Who it's for
You are building | What you get |
An agent or assistant that needs memory | A memory API with forgetting that removes facts from the store, and an MCP server for editors and agent hosts |
A local-first or offline app | Embedded search and storage in one directory, with no server process and optional encryption |
A service that needs vector or text search |
|
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 contains no hosted service. WritersLogic sells WARM Sync, a separate encrypted multi-device sync service with its own client package; the engine here does not contact it.
To try the offline memory demo from source:
git clone https://github.com/writerslogic/warm
cd warm
cargo run --release --example demo-offline-agentFrom 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-rustThe 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, SearchOptions, WarmCore};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// A store is a directory; it persists there and reopens with the same arguments.
let dir = std::env::temp_dir().join(format!("warm-quickstart-{}", std::process::id()));
let warm = WarmCore::new(4096, Some(dir.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: None,
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);
drop(warm);
std::fs::remove_dir_all(&dir)?;
Ok(())
}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.
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 warm-sdk@0.2.1Check the available npm versions. To build the client from this checkout (the build needs Node 20.19 or newer; the built client and the published package run on Node 18):
npm ci --prefix bindings/js/warm-sdk
npm run build --prefix bindings/js/warm-sdkIn your application, install that directory with
npm install /absolute/path/to/warm/bindings/js/warm-sdk.
Start the server in a separate terminal:
curl -fsSL https://raw.githubusercontent.com/writerslogic/warm/main/scripts/install-warm-server.sh | sh
WARM_API_KEY=change-me warm-server --input-dim 384The installer downloads a prebuilt, checksum-verified binary from the server-v<version> GitHub
release (Linux glibc x86_64 and aarch64, macOS, no Alpine). To build it yourself instead:
cargo build --release --features server --bin warm-server.
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.mjsSee the client API and release availability. Browser deployments must permit the application's origin at the HTTP service boundary.
writerslogic-warm embeds the Rust engine in Node. For a published engine release,
install it explicitly with npm's optional dependencies enabled:
npm install writerslogic-warm@0.6.8Check the available npm versions. To build from the cloned repository, with Rust installed:
npm ci --omit=optional
npm run buildThe 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) })The Python package warm-sdk is an HTTP client for warm-server, which stores vectors you
supply. warm-python (imported as writerslogic_warm) is the in-process native package: vector
indexes and phase vectors in 0.6.8, which has no document search. The in-process Warm class
(document search, remember, recall, forget, explain) is on main and ships with the
release after 0.6.8; until then, maturin develop --release from a checkout provides it.
curl -fsSL https://raw.githubusercontent.com/writerslogic/warm/main/scripts/install-warm-server.sh | sh
WARM_API_KEY=change-me warm-server --input-dim 384 &
uv pip install warm-sdkfrom 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
(memory API plus a toy-embedder vector section; uv run --no-project --with warm-sdk) is in examples/quickstart/python.
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
uvx warm-mcp # the same launcher from PyPI
npx -y writerslogic-warm-mcp --transport http # http://127.0.0.1:8765/mcpThe 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/mcpClient setup, data directory and the one-writer rule: MCP integration.
For normalized content from multiple applications, see the organizational knowledge adapter.
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.
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
Capability | Status | Documented limit |
Hybrid document search (BM25 + exact cosine, filters, byte offsets) | Ships | Exact scan of eligible chunks; benchmark your corpus before assuming capacity (guide) |
Boolean lexical search ( | Ships | Flat queries only, no nesting; an empty or only-excluded query matches nothing (design) |
Atomic replace/delete, crash-safe journal, verified compaction, process lock | Ships | One writer per store; compaction is not secure erasure |
Vector index ( | Ships | Builds slower than hnswlib at M=16 and M=32 on SIFT-1M (results); behind ScaNN and faiss-ivfpqfs on single-core ann-benchmarks at recall 0.95: SIFT 2,819 against 3,787 QPS ( |
Updatable vector index (durable delta for inserts and deletes) | Ships | Single 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, explain | Ships | Forgetting removes a fact from the store; it does not cover what a model inferred (docs) |
Conversation memory ( | Ships | Bounded context with exact source provenance; native recall not yet benchmarked on LongMemEval end to end |
Meaning memory: triples, multi-hop, Hopfield cleanup | Ships (runtime opt-in) | Tested on synthetic and 2,120-fact sets ( |
Union-bundle membership ( | Research | At D = 16,384: positive gap to N = 500 (4% false positives), tested to 2,500 ( |
Vector API ( | Ships | Backed by the updatable vertex graph; glove-100 recall@10 0.859 at 2,092 QPS on one thread of an Apple M4, below hnswlib's QPS ( |
Encrypted stores ( | Ships | AES-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_Sign1 over Ed25519, | Ships | Host must authenticate DIDs; PoSME, RATS, |
On-device models ( | Ships | Local weights only; never downloads |
| Ships | Single node; TLS, per-tenant scoped keys (guide) |
MCP server ( | Ships | Encryption needs |
JavaScript/TypeScript client ( | Source and release builds | Portable HTTP client; requires a separately running server |
Embedded Node.js ( | Source and release builds | Eight optional native platform packages; separate from the client |
C, Go, .NET, Java, Kotlin, Swift and WebAssembly bindings | Source available | Require local builds; the language packages and native bundles are not yet published (runtime guides) |
Python | HTTP client ( | No in-process document search |
Query-private search ( | Experimental | For 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 --> cryptoModule 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: falsekeeps 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.
Available Tools
8 toolsexportExport memory contentsARead-onlyIdempotent
Read a portable snapshot of memory contents as JSON, JSONL or Markdown; use list for short previews instead. Read-only. The payload is returned as text and capped by the server's export byte limit; pass next_cursor as cursor to continue.
Inputs: tag, limit, cursor, format, +1 more. Returns: bytes, count, format, next_cursor
forgetDelete memoriesADestructiveIdempotent
Delete memories from the active store by id, ids or id prefix; use remember to update content instead. Inspect prefix matches with list first: prefix deletion requires confirm: true. Returns the deletion count and ids that were absent.
Inputs: id, ids, prefix, confirm. Returns: deleted, missing
getGet memoryARead-onlyIdempotent
Read one known memory id in full, including tags, metadata and version. Use an id from list or search; use recall when only a natural-language question is known. Read-only; an unknown id returns an error.
Inputs: id (required). Returns: memory
listList memoriesARead-onlyIdempotent
Browse memories in id order, optionally limited by id prefix or tag; use search for relevance ranking. Read-only. Returns text previews unless full is true; pass next_cursor as cursor to continue.
Inputs: tag, full, limit, cursor, +1 more. Returns: count, memories, next_cursor
recallRecall matching memoriesARead-onlyIdempotent
Retrieve full memories ranked for a natural-language question. Use this for ordinary recall; use search when you need metadata filters, ranking controls or score details. Read-only; default builds rank lexically, and a configured model adds semantic ranking.
Inputs: query (required), k, tags, min_score. Returns: count, results
rememberStore memoryADestructive
Store a durable fact, decision or preference; use recall to find one instead. A supplied id replaces that memory, while an omitted id creates a new one. Use if_version to reject concurrent changes or create_only to reject overwrites.
Inputs: text (required), id, tags, title, +4 more. Returns: id, bytes, created, version, +1 more
searchSearch memory with filtersARead-onlyIdempotent
Find memories with metadata filters or ranking controls; use recall for simpler full-text answers. Read-only. Results contain text previews and relative ranking scores, not probabilities; use get to read a result in full. Semantic scores require a configured model.
Inputs: query (required), k, tags, filter, +4 more. Returns: count, results
statsStore statisticsARead-onlyIdempotent
Inspect store counts, recall mode, encryption status, storage size and active limits without reading memory contents. Read-only; use list to inspect stored memories.
Inputs: no named parameters. Returns: limits, recall, memories, namespace, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation, but `recall` and `search` both perform retrieval and rely on the descriptions to separate natural-language lookup from filtered/ranked lookup; `list` also overlaps with `search` for browsing. The descriptions do a good job of redirecting between them, so an agent is unlikely to misselect in practice.
All names are short, single-word imperative/lowercase tokens (remember, recall, search, get, forget, list, export) with `stats` as the only noun form. The convention is consistent and readable, just not a strict verb_noun pattern.
Eight tools is a well-scoped surface for a memory store: write, several read modes, delete, and two introspection utilities. No tool looks redundant enough to remove, and nothing feels missing at the count level.
Covers the full lifecycle: create/overwrite (remember with id/if_version/create_only), read (get, recall, search, list), delete (forget), diagnostics (stats) and snapshot export. The notable gap is an `import`/restore counterpart to `export`, plus explicit tag/metadata-only mutation, which agents must work around by rewriting content.
Maintenance
Related MCP Connectors
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Memory system for AI agents with semantic search. Store and recall memories with ease.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables Claude AI to seamlessly interact with Scrivener projects for document management, AI-powered content analysis, and advanced writing assistance.57275 npm73AGPL 3.0
- AlicenseAqualityDmaintenancePortable cognitive memory for AI agents with semantic search, decay, and deduplication.816 npm2MIT
- AlicenseAqualityNot gradedmaintenancePersistent memory MCP server for AI agents, using SQLite with hybrid keyword and semantic search for long-term memory storage.5Do What The F*ck You Want To Public
- AlicenseNot gradedqualityBmaintenanceLocal-first, multi-user shared memory for AI agents with semantic search, offline support, and team synchronization.MIT