store_memory: Write-Behind Local Commit in Under 5ms

store_memory is an MCP tool, exposed by @sovseal/mcp-server. It is built around a single operational principle: no tool call ever blocks on I/O. It redacts, embeds, encrypts, writes to the local LanceDB index, and returns — without waiting for the replication endpoint.

store_memory is exposed as an MCP tool by @sovseal/mcp-server. @sovseal/sdk (v1.0.0+) and sovseal-sdk (v1.1.0+) also expose store(content) via framed IPC to the local native host (~/.sovseal/native-host/run.sh). If the native host is absent, version-mismatched (protocolVersion: 1), or times out, SDK calls throw/raise EngineUnavailableError (reason: "not-installed" | "version-mismatch" | "timeout") with zero cloud fallback. See Quickstart.

The write contract

Property	Guarantee
Local durability on return	Yes — committed to disk before the call returns
Remote durability on return	No — replication is asynchronous (write-behind)
Latency p50	3.8 ms
Latency p95	7.2 ms
Latency p99	12.5 ms
Network behavior	0 RTT on the call path
Failure mode if replication is offline	Buffered locally; flushed when the network returns

Reproduce these numbers: pnpm --filter @sovseal/mcp-server test bench-v2.

Arguments

store_memory({ content: string })

That is the entire input schema — a single non-empty content string, length-capped by STORE_MEMORY_MAX_CHARS. There is no path, no metadata, and no parent argument.

Return value

{
  "id": "a86938e9-de49-4a87-89de-edb62bef27b8",
  "reinforced": false,
  "redacted": 0,
  "redactedRules": []
}

id — the local record identifier.
reinforced — true when the content matched an existing memory closely enough to increment reinforce_count instead of inserting a new row.
redacted / redactedRules — how many high-risk PII matches were masked before embedding, and which rules fired. The matched values are never returned or logged.

The write pipeline

Redact high-risk PII

Content passes through the redaction chokepoint before anything else. The always-on trio — SSN, Luhn-validated credit cards, and provider API keys — is masked to [REDACTED:…] tokens. The secret therefore never reaches the vector, the stored row, or the sync envelope.

Embed on-device

The cleaned text runs through the local Xenova/all-MiniLM-L6-v2 ONNX model (quantized, ~22 MB, auto-downloaded to ~/.sovseal/models/ and SHA-256 pinned), producing a 384-dimensional vector. The embedding is stored locally and is never sent to the server.

The MCP server and the browser extension currently run different embedders (Xenova/all-MiniLM-L6-v2 vs. intfloat/multilingual-e5-small) — a same-day integrity-pinning fix reverted a brief mid-development unification. The two surfaces do not currently share one vector space. See logs/escalation/EMBEDDER-minilm-e5-prefix-mismatch.md.

Encrypt at rest

The text field is sealed with AES-256-GCM under k_rest — envelope format sgcm1: + base64(IV‖ciphertext‖tag), with a per-row 96-bit IV and AAD = utf8(id|schema_version). The key is an HKDF subkey of a master that lives in your OS keychain.

Write to LanceDB, or reinforce

If an identical fact already exists, reinforce_count and last_reinforced are updated instead of inserting a duplicate. Otherwise a new Schema-v2 row is written.

Enqueue replication and return

The record enters the write-behind outbox and the call returns. A background SyncWorker seals the snapshot under k_sync and pushes ciphertext to the edge endpoint.

Embedding vectors remain in the clear on the local disk. Only text is encrypted at rest. This is a documented residual, not an oversight — see Zero-Knowledge.

Calling it

// Sent by the AI client
{
  "name": "store_memory",
  "arguments": {
    "content": "I prefer Vitest over Jest for new TypeScript projects."
  }
}

// Response
{
  "id": "a86938e9-de49-4a87-89de-edb62bef27b8",
  "reinforced": false,
  "redacted": 0,
  "redactedRules": []
}

import { AgentStateClient, EngineUnavailableError } from "@sovseal/sdk";

const client = new AgentStateClient({
  endpoint: "https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state",
  apiKey: process.env.SOVSEAL_API_KEY!,
});

// Communicates over framed IPC with ~/.sovseal/native-host/run.sh.
// Throws EngineUnavailableError if host is absent or version mismatched.
try {
  const result = await client.store("I prefer Vitest over Jest for new TypeScript projects.");
  console.log(result.id, result.reinforced);
} catch (err) {
  if (err instanceof EngineUnavailableError) {
    console.error(`Host unavailable: ${err.reason}, install at ${err.installUrl}`);
  }
}

Failure modes

Failure	What happens
Local disk is full	The write rejects before commit; no record is created
Replication endpoint returns 4xx / 5xx	Local write is unaffected; the record stays in the outbox and retries
Network is offline	Same — buffered locally, flushed on reconnect
Process crashes after commit	The record survives locally; the outbox re-flushes on next start
Payload exceeds the chunk cap	Rejected at the edge with `413` — the ciphertext cap is 256 KB, see Limits & SLAs

The design invariant: replication failures can never lose or block a local write.

What reaches the server

Only what is needed to store and later restore an opaque blob:

agent_id — sha256(project_id ‖ ":" ‖ key). The server never learns the raw key name.
ciphertext — AES-256-GCM sealed under k_sync.
client_payload_hash — sha256(canonicalize(payload)), the integrity anchor for Verified Semantic Recall.
sequence_number, parent_snapshot, timestamp — lineage metadata.

Never sent: the plaintext, the encryption key, or the embedding vector.

Next steps

recall_memory

How stored records become ranked query results — locally, with zero RTTs.

Verified Semantic Recall

What prevents a malicious server from substituting your ciphertext on restore.

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

store_memory: Write-Behind Local Commit in Under 5ms

The write contract

Arguments

Return value

The write pipeline

Calling it

Failure modes

What reaches the server

Next steps

recall_memory

Verified Semantic Recall

​The write contract

​Arguments

​Return value

​The write pipeline

​Calling it

​Failure modes

​What reaches the server

​Next steps

recall_memory

Verified Semantic Recall

The write contract

Arguments

Return value

The write pipeline

Calling it

Failure modes

What reaches the server

Next steps