Quickstart — Semvec REST API for semantic memory (5 min)¶

The lowest-friction way to try Semvec is the REST API: one semvec serve command, then call HTTP from any client. No Python integration required, every endpoint shape and JSON schema is fixed.

For tighter per-turn latency, in-process state sharing, or custom embedders inside the host process, drop into the Python library quickstart further down.

Prerequisites¶

Python 3.10 or newer (python --version)
An embedder. Cheapest: pip install sentence-transformers

REST API quickstart¶

Install¶

pip install "semvec[api]" sentence-transformers

Start the server¶

semvec serve --port 8001

Server is ready when it logs Uvicorn running on http://0.0.0.0:8001.

Call it¶

# 1. Health check
curl -s http://localhost:8001/v1/health
# → {"status":"ok"}

# 2. Create a session and run a turn
curl -s -X POST http://localhost:8001/v1/run \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "demo",
    "input": "We currently support SEPA payments but not iDEAL.",
    "store": true
  }'

# 3. Ask a follow-up — the context block is built automatically
curl -s -X POST http://localhost:8001/v1/run \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "demo",
    "input": "Which markets does iDEAL unlock for us?"
  }'

The context field returned by /v1/run is the constant-cost input you pass to your LLM, instead of the growing transcript. Whether the conversation has run for 3 turns or 30 000, the size stays bounded.

See the REST API reference for the full endpoint catalogue, the CLI reference for semvec serve flags and SEMVEC_* environment variables.

You are productive

If /v1/health returns 200 and /v1/run returns a context block, you have a working Semvec. Move on:

Choose your path — when to graduate to the in-process library
Full tour (15 min) — every surface end-to-end
Concepts & Glossary — phases, tiers, anchors, triggers
Embedders — pick a different model

Python library quickstart¶

For applications that need tighter latency than the REST round-trip, or in-process control over embedders and state, use the library directly.

Install¶

pip install semvec sentence-transformers

Minimal example¶

from semvec import SemvecState, SemvecConfig
from sentence_transformers import SentenceTransformer

# 1. Set up Semvec + your embedder
model = SentenceTransformer("all-MiniLM-L6-v2")
# dimension MUST match your embedder's output size.
# all-MiniLM-L6-v2 = 384, all-mpnet-base-v2 = 768,
# OpenAI text-embedding-3-small = 1536.
# Mismatch raises EmbeddingError at the first state.update().
state = SemvecState(config=SemvecConfig(dimension=384))

# 2. Feed it a conversation, turn by turn
conversation = [
    "I want to discuss our European customer onboarding flow.",
    "We currently support SEPA payments but not iDEAL.",
    "Which markets does iDEAL unlock for us?",
]
for text in conversation:
    result = state.update(model.encode(text), text)
    print(f"phase={result['phase']:14}  fsm={result['fsm']:.3f}")
# phase: conversation stage (initialization / exploration / convergence / resonance / stability / instability)
# fsm:   stability score in [0, 1] — gate expensive actions on fsm > 0.7
# See concepts-glossary.md for the full list of metrics returned by update().

# 3. Get a compact context block for the next LLM call
from semvec.token_reduction import SemvecStateSerializer
context = SemvecStateSerializer().serialize(state, query_text="Should we add iDEAL?")
print(context[:400], "...")

The context string above is the same compact block that /v1/run returns — just produced in-process instead of over HTTP.

Common stumbles¶

Error	Fix
`ImportError: No module named 'sentence_transformers'`	`pip install sentence-transformers`
`RuntimeError: Explicit embedder required`	You called a surface that needs `embedder=` — pass one in, or install `sentence-transformers` to let Semvec auto-load the default.
`EmbeddingError: dimension mismatch`	Your model and `SemvecConfig.dimension` disagree. Set `dimension=` to match (384 for MiniLM, 1536 for OpenAI `text-embedding-3-small`).
REST `/v1/run` returns 503	Embedder not ready. Wait for the `Uvicorn running on` log line, or pre-warm with `/v1/health`.
REST `/v1/run` returns 401	Endpoint requires a licence JWT. Set `SEMVEC_LICENSE_KEY="eyJ..."` (Pro / Enterprise key, or a Community evaluation key issued via `vertrieb@versino.de`) before starting `semvec serve`. The `SEMVEC_ALLOW_ANONYMOUS=1` development bypass only works in wheels built locally with `maturin develop --features dev-anonymous` — it is not available in the PyPI release wheel.

More symptoms and fixes in Troubleshooting.