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.

Command-line flags are available for the three deployment settings most often changed by a service manager. Flags override environment defaults:

seam-self-host --host 127.0.0.1 --port 8830 --db /srv/seam/state.db

GET and HEAD on /v1/health are unauthenticated. The endpoint performs a cached storage-readiness check: healthy nodes return 200; a node whose configured store cannot answer a trivial read returns 503 without disclosing the backend or connection error.

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.

Treat the built-in option as a keyword-search baseline, not a semantic embedding model. In a deterministic characterization with 100 memories and 41 queries, its measured recall was:

On the same fixed queries, recall@1 fell from 0.786 at 20 memories to 0.500 at 100. Use openai, openai-compatible, or a qualified local semantic model for paraphrase-heavy or larger corpora. The offline default is preserved so a new installation never silently requires an account or network call.

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

Successful and failed guarded requests both consume the rate-limit bucket. Authenticated requests are keyed by a one-way digest of the authorization header, so every client using the node's one valid token shares a bucket. Requests without that header are keyed by the direct socket peer. Forwarding headers are deliberately ignored; behind a reverse proxy, unauthenticated requests therefore share the proxy's bucket. A 429 response includes Retry-After: 60. Use the proxy's own trusted-client rate limiter for per-user enforcement, and do not treat this in-process limiter as a multi-node quota system.

Request limits

Text, query, and partition fields must be JSON strings; objects, arrays, numbers, and booleans are rejected rather than converted into Python text.

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_API_RATE_LIMIT_PER_MINUTE, SEAM_API_RATE_LIMIT, 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

Outside a writable container layout, seam-mcp needs no arguments: it defaults to ${XDG_DATA_HOME:-~/.local/share}/seam/seam.db. An explicit --db wins over the environment. Without the flag, SEAM_SERVER_DB wins over SEAM_DB_PATH; the user-data default applies only when neither contains a path.

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.