Embedded mode

Status

Embedded mode is not shipped. The current SDKs are HTTP-only. There is no in-process embedded build; there are no napi-rs or pyo3 bindings exposed publicly. The Rust workspace explicitly omits SQLite from the supported backends.

The reason is focus, not technical impossibility. Recall v0.x is optimised for the cloud + self-hosted-Postgres path; embedded mode would multiply the testing surface (every pipeline stage tested twice, once per backend) without enough customer pull to justify the cost yet.

What embedded mode would look like

If shipped, embedded mode would offer:

• A recall-sqlite crate implementing the same Storage trait as recall-pg, backed by SQLite + sqlite-vec
• napi-rs bindings exposing the pipelines via Node.js native modules
• pyo3 bindings exposing the pipelines via Python native modules
• A single in-process database file (recall.db) instead of a Postgres connection
• The same six-stage write pipeline and eight-stage read pipeline, just running locally

The HTTP API would still exist; embedded mode would be an additional consumer of the same pipeline crates, not a replacement.

Why "single codebase" matters

Design wedge #1 is: one codebase across self-host and cloud. The original spec extends that to embedded mode — same write pipeline, same read pipeline, same retrieval semantics, regardless of where the bytes live. A pipeline change should ship to all three deployment shapes simultaneously, not require a fork.

This is what makes the wedge expensive. Adding a new retrieval strategy (say, a graph-walk variant) requires implementing it for both Postgres and SQLite + retesting both. Until customer demand justifies the testing matrix, embedded stays deferred.

Workarounds today

For local dev: Docker Postgres

The lightest equivalent of "embedded" is the official Docker image with Postgres on the same machine:

docker run -d --name recall-pg \
  -e POSTGRES_USER=recall \
  -e POSTGRES_PASSWORD=recall \
  -e POSTGRES_DB=recall \
  -p 5432:5432 \
  pgvector/pgvector:pg16

You're off-process from Recall but still running locally. The latency penalty is ~5-10 ms per call (loopback Postgres), which is fine for development.

For tests: stub Storage

The recall-storage crate ships an in-memory StubStorage for unit tests. It implements the Storage trait against Vec/HashMap collections — fast, deterministic, no I/O. SDK consumers don't have access to this; it's an internal testing tool only.

For agents that need a single binary: HTTP loopback

Bundle recall-server and Postgres in your application's container; talk to localhost. This is the "embedded-ish" pattern most early adopters use.

When embedded ships

The roadmap signals to watch:

1. Sufficient customer requests for in-process Recall to justify the testing matrix
2. sqlite-vec stability (the extension is younger than pgvector)
3. napi-rs bindings infrastructure landed in the workspace

When it ships, this page will be replaced with concrete setup instructions. Until then, treat embedded as not-shipped and budget accordingly.