Choose your path

Recommended starting point: the REST API. semvec serve exposes the full feature surface over HTTP with a single binary, no Python integration required — every endpoint shape, error model, and JSON schema is fixed. The in-process Python library is the next step once the integration outgrows the HTTP boundary (tight per-turn latency, shared in-process state, custom embedders inside the host process).

Decision tree

flowchart TD
    Start{"Where to start?"}
    Start --> Q0{"Running a coding agent?<br/>(Claude Code, Cursor, …)"}
    Q0 -->|Yes| MCP["0. Coding-agent MCP server<br/>semvec.coding.mcp_server<br/>→ semvec[coding]"]
    Q0 -->|No| REST["1. REST API (recommended start)<br/>semvec serve · curl / httpx<br/>→ semvec[api]"]
    REST --> Q1{"Need multi-agent<br/>coordination?"}
    Q1 -->|Yes| CORTEX_REST["2. Cortex over REST<br/>/v1/cluster/* · /v1/region/*<br/>(distributed-ready, no Python required)"]
    Q1 -->|No| Q2{"Need tighter per-turn<br/>latency or in-process<br/>control?"}
    Q2 -->|No| StayREST["Keep the REST integration"]
    Q2 -->|Yes| LIB["3. In-process Python library<br/>SemvecState · SemvecChatProxy<br/>→ semvec"]
    LIB --> Q3{"Multiple in-process<br/>agents sharing state?"}
    Q3 -->|Yes| CORTEX_INPROC["4. Cortex in-process<br/>(SemvecAgentNetwork)"]
    Q3 -->|No| STATE["SemvecState alone"]

Path summary

#	Path	Fit	What you do
1	REST API (semvec serve)	Default start. Polyglot stacks, microservices, lowest setup friction.	pip install semvec[api], semvec serve --port 8001, then curl or httpx.
2	Cortex over REST	Multi-agent coordination at the HTTP boundary. Distributed-ready, no Python integration required. Easier to set up than in-process Cortex.	semvec serve + the /v1/cluster/* and /v1/region/* endpoints.
3	In-process SemvecState	Single Python agent that needs tight per-turn latency, custom embedders, or shared in-process state.	pip install semvec, from semvec import SemvecState.
4	Cortex in-process (SemvecAgentNetwork)	Already on the in-process library and want multiple agents in the same Python process.	pip install semvec, see Cortex guide.
5	Coding-agent integration	Power Claude Code / Cursor compaction via MCP.	Coding agents.
6	Compliance pack on top	Regulated workloads (audit, retention, deletion proofs). Layers onto any path above.	Compliance pack.

Common questions

"Do I need Cortex?" Only if more than one agent has to share or hand off context. A single chatbot does not need Cortex.

"Can I run without writing Python?" Yes — semvec serve exposes every operation as REST endpoints; curl, httpx, or any HTTP client works.

"Do I have to choose between in-process and REST?" No. You can start in-process, expose semvec serve later, and swap clients without changing state semantics.