seam-self-host

seam-self-host is the compiled Linux/x86-64 self-hosted SEAM agent-memory node. It installs the opaque /v1 service plus the local MCP stdio surface used by Claude, Cursor, Gemini, and other MCP-capable agents.

The wheel contains native extension modules and does not ship the seam_runtime Python source. Native compilation raises the cost of casual inspection; it is not a cryptographic boundary against an administrator who controls the host. See the self-host security documentation for the complete protection model.

This first wheel supports CPython 3.12 on manylinux_2_28_x86_64.

Run

The node needs only an API token of at least 32 characters and a writable database path. It runs with no third-party account:

export SEAM_API_TOKEN_FILE=/run/secrets/seam-api-token
export SEAM_SERVER_DB=/var/lib/seam/seam.db
seam-self-host

The server listens on 0.0.0.0:8765 by default. Keep it on a trusted network or place an authenticated TLS reverse proxy in front of it.

Configuration

Everything below is optional. Defaults are chosen so a fresh install works offline; the settings that most affect answer quality are in the first two tables.

Retrieval quality

The single highest-impact setting. Retrieval depth and context size are tuned together, because the right pair depends on how capable the model consuming the context is. Shipping defaults are deliberately conservative.

Start with SEAM_RETRIEVAL_PROFILE=compact. Move to broad only if the model reading the context is a frontier-class one.

Embeddings

The built-in embedder is the default. It needs no network, no account, and no per-request cost, which is why a fresh install just runs. It is lexical, so paraphrased recall ("how often does the key rotate" against "key rotates every 90 days") is weaker than a semantic model. Switching is the main quality upgrade after the retrieval profile.

Selecting an API provider without its key is refused at startup rather than failing on the first write. sentence-transformers is not bundled; install it yourself if you want local semantic embeddings.

Changing the provider changes how vectors are computed. Existing memories keep their old vectors, so re-ingest if you switch after storing data.

Retrieval ranking

Defaults reproduce the shipped ranking exactly. Change one at a time and measure; these interact.

Context and answer policies

All default to the baseline single-pass path. They change the shape of the context returned to your model, not just its ranking.

Storage

SQLite is the default and is sufficient for a single node. Use Postgres when you need several nodes against one store. Run one writer per database either way.

Extraction

Off by default: ingest uses a deterministic parser that needs no model. The optional extractor sends memory text to a local Ollama server, which improves entity and relation quality and is what makes SEAM_RETRIEVAL_ENTITY_GROUNDED useful.

Server

Entitlement

Optional, and gates no capability. Absence is the normal free path.

Present but not used by this edition

These are read by code compiled into the binary but are not reachable through the /v1 routes or the MCP surface. Setting them has no effect here; they are listed so the set is complete rather than mysterious:

SEAM_API_CORS_ORIGINS, SEAM_API_TREE_ROOT, SEAM_API_TREE_MAX_DEPTH, SEAM_API_TREE_MAX_ENTRIES, SEAM_API_ALLOW_BENCHMARK_HOLDOUT, SEAM_API_CONFIRM_HOLDOUT, SEAM_CHAT_ALLOWED_HOSTS, SEAM_WEBUI_DIR, SEAM_DB_PATH, SEAM_INSTALLER_USER_PATH, SEAM_SURFACE_DIR, SEAM_SURFACE_MAX_PAYLOAD_BYTES, SEAM_DERIVED_FACTS_POLICY, SEAM_SENTENCE_FACT_MODEL, SEAM_SENTENCE_FACT_NUM_PREDICT, SEAM_API_ALLOW_REMOTE_NO_TOKEN, SEAM_API_ALLOW_INSECURE_REMOTE, SEAM_API_ALLOW_PROCESS_LOCAL_RATE_LIMIT, and the SEAM_JSPACE_* family.

The three SEAM_API_ALLOW_* names are worth calling out: they relax authentication and transport checks on the full runtime's REST server, which this edition does not start. They cannot be used to weaken the /v1 surface's bearer-token requirement.

A reasonable production start

export SEAM_API_TOKEN_FILE=/run/secrets/seam-api-token
export SEAM_SERVER_DB=/var/lib/seam/seam.db
export SEAM_SELFHOST_HOST=127.0.0.1          # behind a TLS reverse proxy
export SEAM_RETRIEVAL_PROFILE=compact        # or broad, for a frontier model
# optional semantic embeddings:
# export SEAM_EMBEDDING_PROVIDER=openai
# export OPENAI_API_KEY=sk-...
seam-self-host

The node prints its resolved configuration at startup — entitlement state, embedding provider, and vector backend — so you can confirm what it actually picked up.

An entitlement is optional and gates no capability. When no entitlement is mounted, the node logs that it is running unentitled under BUSL-1.1. Supported deployments may set SEAM_SELFHOST_ENTITLEMENT_PATH and SEAM_SELFHOST_PUBLIC_KEY_PATH; a mounted entitlement is verified and a forged or malformed one fails closed.

MCP

Connect an MCP client to the wheel's stdio command:

seam-mcp --db /var/lib/seam/seam.db

The MCP server exposes the same three operations as the HTTP surface — seam_remember, seam_recall, and seam_context — talking directly to the local database instead of over the network. Run it only for a trusted local client and protect the database with operating-system permissions.