Tortoise Documentation

The data model

Everything is a Point: an atomic claim with an id, content (text), pointKind, and a status. The core kind vocabulary (ontology v3.1 §5) is: statement, decision, vision, strategy, plan, goal, target, observation, hypothesis — plus evidence and domain kinds registered by expansion packs.

The hosted API currently accepts a subset: statement, decision, evidence, observation, hypothesis (tracked in issue #7881). The graph and SDK accept the full vocabulary.

• status: draft — created but not yet connected (not counted in confidence)
• status: live — promoted when its first edge is created (#131); participates in confidence computation
• outdated / archived — superseded or retired

A content hash (SHA-256 of content) is stored on every Point; creating the same content twice returns the existing Point (dedup) instead of duplicating.

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 by solving the linear system

(I − λM)g = a

where M is the row-normalized adjacency of IMPL/NAND edges, a is a seed vector (1.0 for resolution-event Points, 0 otherwise), and λ = 0.6 is the propagation dampening. The solution g is each Point's grounding — the steady-state belief given the graph's evidence. Adding a supporting edge raises a Point's score; adding a NAND edge lowers it. Grounding is computed via the SDK (projection.compute_grounding()); the hosted API exposes per-Point confidence values on search/read results.

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 currently produces :Session nodes; alignment is tracked in issue #7882.

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/signup. You'll get an API key on the welcome page — 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), .cursor/mcp.json (Cursor), or claude_desktop_config.json (Claude Desktop). Restart your client.

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 welcome page includes a ready-to-copy MCP config with your key pre-filled.