Tortoise Documentation

The data model

Everything is a Point: an atomic claim with an id, content (text), pointKind, and a status. The kind vocabulary is statement — the asserted belief — plus the write kinds decision, vision, strategy, plan, goal, target, observation, hypothesis, humanApproval, and any domain kinds registered by expansion packs. Canonical vocabulary: docs/ONTOLOGY.md §4.1 and §5. (evidence is an additional kind the SDK registers for decision records. event exists only internally, as the kind on captured episodic turns — it is not a supported write kind: the REST point-create endpoint and the SDK's bundle validator reject it, while create_point only warns.)

The hosted API, the SDK and the graph draw on the same kind vocabulary, plus whatever your expansion packs register.

• status: draft — created but not yet connected (not counted in confidence)
• status: live — promoted when its first edge is created; participates in confidence computation
• status: superseded — replaced by a newer Point, which is linked to it, so the old claim is kept rather than deleted
• status: retracted — withdrawn with no replacement; kept as a tombstone
• outdated — a legacy server-managed flag, kept as a back-compat status value, set alongside supersession or an explicit invalidation
• status: archived — retired

A content hash (SHA-256 of content) is stored on every Point. With dedup enabled — the default over MCP — creating the same content twice returns the existing Point instead of duplicating it; the REST endpoint defaults dedup to false and will create a second Point.

Edges (operators)

Points are connected by operators. The two epistemic edge types are:

• IMPL — source implies target. If you believe A and A implies B, that supports B.
• NAND — source contradicts target. Recorded explicitly rather than deleting either belief, so the graph keeps the tension and confidence reflects it.

Part/whole edges (composedOf, decomposesInto, contains, wraps) and provenance edges (wasDerivedFrom, aboutSubject, …) also exist and are transferred on supersede.

Confidence (EP)

Each live Point carries a belief score. Tortoise computes it with expectation propagation (tortoise/ep.py, read back via sdk.get_confidence()): evidence is passed back and forth along the IMPL/NAND edges until the values settle. Support pulls a Point's belief up; a NAND edge pulls it down. Both remain in the graph, so the disagreement stays visible instead of being resolved by deleting one side.

The result is a distribution, not a single number — a mean and a variance. A tight spread means the evidence has settled; a wide spread means the posterior is weakly determined — thin evidence, or evidence pulling in opposite directions — which is how a Point gets flagged as contested. The hosted API exposes the mean as confidence on search and read results.

Confidence is derived, never a stored verdict. Change the evidence — add a claim, supersede one, record a contradiction — and the affected scores recompute.

Sessions & provenance

Agent conversations are captured as Session nodes (with turn counts and metadata). Points created from a session are linked to it, so every insight traces back to the conversation that produced it. Listing sessions and their linked Points is a first-class API operation.

The ontology defines a richer episodic Event model (eventKind, startedAt/endedAt, produces/uses edges). The hosted API produces :Session nodes, and each capture commit also writes an AgentSession Event carrying the capture timestamp and the session summary.

Search

Search fuses three strategies with RRF (Reciprocal Rank Fusion): full-text search (FTS) on content/title/name, vector similarity (embeddings, when available), and structural matches. Results are ranked by fused relevance, not recency.

1. Create an account

Sign up at tortoise.premiselabs.co/auth. You'll get an API key in the in-app welcome card — copy it. It's shown once.

2. Write your first Point

curl -X POST https://api.premiselabs.co/v1/points \
  -H "Authorization: Bearer tt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "the production port is 16379", "kind": "statement"}'

Response includes the Point's id.

3. Search

curl "https://api.premiselabs.co/v1/search?q=port" \
  -H "Authorization: Bearer tt_YOUR_KEY"

Returns ranked results (FTS + vector + structural, RRF-fused).

4. Manage in the dashboard

Open app.premiselabs.co, paste your key, and you can create/revoke API keys and view sessions.

Setup — hosted (no install)

Add this to your MCP config (replace tt_YOUR_KEY with your API key):

{
  "mcpServers": {
    "tortoise": {
      "type": "streamable-http",
      "url": "https://api.premiselabs.co/mcp/",
      "headers": {
        "Authorization": "Bearer tt_YOUR_KEY"
      }
    }
  }
}

Paste into .mcp.json (Claude Code) or .cursor/mcp.json (Cursor). Restart your client. For Claude Desktop, add the server from Settings → Connectors → Add custom connector instead — claude_desktop_config.json only accepts local stdio servers, so a remote HTTP server placed there is silently ignored.

The hosted MCP server runs on our infrastructure over Streamable HTTP — no Python or tortoise install needed. Your client just needs network access to https://api.premiselabs.co/mcp/.

Setup — self-hosted (stdio)

Running Tortoise on your own infrastructure? Point the MCP client at a local process over stdio instead (see the self-hosted guide):

{
  "mcpServers": {
    "tortoise": {
      "command": "python3",
      "args": ["-m", "tortoise.mcp_server"],
      "env": {
        "TORTOISE_API_KEY": "tt_YOUR_KEY",
        "TORTOISE_API_URL": "https://api.premiselabs.co"
      }
    }
  }
}

Need python3 and tortoise installed where the client runs? pip install tortoise-graph — the MCP server ships with the package.

What your agent can do

• Remember: tortoise_create_point — store a decision, observation, or claim
• Recall: tortoise_search — query the past with hybrid search
• Reason: tortoise_compute_confidence — see how evidence propagates
• Structure: tortoise_create_operator, tortoise_traverse, tortoise_entity_profile, and more

Your in-app welcome flow includes a ready-to-copy harness setup with your key pre-filled.