operator manual · cli · mcp · surfaces

SEAM Documentation

Everything you need to install, drive, and integrate the SEAM memory runtime — the canonical store, the CLI surface, the MCP agent bridge, and readable holographic surfaces.

╭─ The 60-Second Demo ─╮ ⏱ ≈ 60s · zero to context
bash — seam

Init a store · ingest a file · compile to MIRL · search · retrieve in mix mode · serve the dashboard.
╭─ Install ─╮

Get SEAM running.

One-line install from the private repo. Requires gh auth login first. The runtime serves its dashboard directly — no Node build step.

One-line install

gh repo clone BlackhatShiftey/Seam Seam \
  && cd Seam \
  && sh ./installers/install_seam_linux.sh

Repo-local development

gh repo clone BlackhatShiftey/Seam Seam \
  && cd Seam \
  && sh ./installers/install_seam_linux.sh --dev

If Debian/Ubuntu reports venv missing: sudo apt-get install -y python3-venv

One-line install

gh repo clone BlackhatShiftey/Seam Seam; cd Seam; `
  powershell -ExecutionPolicy Bypass `
  -File .\installers\install_seam_windows.ps1

Repo-local development

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e ".[dash]"
.\.venv\Scripts\python.exe seam.py doctor

Verify in a new terminal

seam doctor
seam --help
seam dashboard --snapshot --no-clear
SEAM doctor: PASS Compile smoke: PASS Required deps: OK

First memory flow

seam ingest README.md --persist
seam memory search "persistent memory"
seam retrieve "persistent memory" --mode mix --budget 5
seam context "persistent memory" --retrieval-mode mix --view prompt
╭─ CLI Reference ─╮

The seam command surface.

The operator-facing composition surface. Every interface — CLI, MCP, REST, dashboard — calls the same shared runtime behavior.

{{ group.title }}
{{ cmd.cmd }} {{ cmd.desc }}
╭─ Operator Manual ─╮

Driving the runtime.

A practical runbook for interacting with SEAM, running tests, and validating the live stack. SQLite is canonical truth; vector stores are rebuildable acceleration.

What SEAM uses

  • › SQLite for canonical truth, provenance, packs & metadata
  • › SQLite vector_index by default for local vector search
  • › Optional Postgres + pgvector (port 55432)
  • › Local deterministic hash embeddings, or an OpenAI-compatible provider

Where data lives

  • › Truth DB — whatever you pass to --db
  • › Vector index — inside that same SQLite file unless pgvector is enabled
  • › pgvector — separate container seam-pgvector on localhost:55432

Compile, search, retrieve

seam --db seam.db compile-nl "We need a translator back into natural language."
seam --db seam.db search "translator natural language" --budget 3
seam --db seam.db retrieve "translator natural language" --mode mix
seam --db seam.db pack clm:2,sta:ent:project:seam --mode context --budget 128
seam --db seam.db trace clm:2

SEAM emits RAW, SPAN, PROV, ENT, CLM, and STA records. Results show lexical, semantic, graph, and temporal contribution reasons, with the evidence chain attached.

Recommended test loop

python -m pytest test_seam_all/test_seam.py -q
seam doctor
seam --db seam_validate.db stats
╭─ Retrieval & RAG ─╮

Six signals. One orchestrator.

SEAM ranks evidence through six modes. Use mix for agent RAG unless a benchmark says another mode wins. Retrieval builds a compact PACK only after records are selected.

{{ m.name }}
{{ m.desc }}

Progressive disclosure

seam memory search "benchmark gate"          # compact: IDs, summaries, scores
seam memory get clm:1,clm:2 --timeline       # full MIRL for selected records only
seam retrieve "persistent memory" --mode mix --budget 5 --trace
seam reindex                                 # refresh stale derived vectors

Agents inspect IDs and scores first, then fetch full MIRL only for selected records — keeping prompt cost low. SQLite stays canonical; vectors and graph edges are rebuildable.

╭─ MIRL & Surfaces ─╮

Readable, lossless memory.

MIRL is the canonical memory IR. The compressed artifact must be directly readable machine language — answerable without restoring the original document. SEAM-RC/1 is readable text compression; SEAM-HS/1 folds payloads into the RGB channels of a lossless PNG.

Record kinds

{{ k }}
SEAM-RC/1 · readable compression
seam readable-compress input.txt --output input.seamrc
seam readable-query input.seamrc '"exact quoted text"'
seam readable-rebuild input.seamrc --output rebuilt.txt
SEAM-HS/1 · holographic surface
seam surface compile input.txt --output input.seam.png --mode rgb24
seam surface query input.seam.png "exact phrase"
seam surface verify input.seam.png

Only lossless PNG surfaces are exact memory artifacts in v1 — lossy formats like JPEG are rejected for exact-read workflows. rgb24 is the default density mode; rgba32 / rgba64 store higher density.

╭─ MCP Integration ─╮

The agent bridge.

seam mcp stdio starts a standards-compliant MCP JSON-RPC server over stdio. Gemini CLI, Claude Desktop, Cursor, OpenCode, and other MCP clients configure it as a local stdio server.

{
  "mcpServers": {
    "seam": {
      "command": "python",
      "args": ["-m", "seam_runtime.mcp_protocol", "--ensure-pgvector"],
      "cwd": ".",
      "timeout": 120000,
      "trust": false
    }
  }
}

Discovered tools

{{ t }}
╭─ Troubleshooting ─╮

When something fails.

The current playbook. Most issues are environment state — set the env var in the same shell session and re-run seam doctor.

Symptom Fix
{{ f.symptom }} {{ f.fix }}