title: "Tortoise — Semantic + Epistemic + Episodic + Procedural Graph Engine" type: readme domain: epistemic status: live created: 2026-07-24 updated: 2026-08-07

Tortoise

A graph engine for agent memory: claims are Points, relationships are edges, and belief scores are computed by propagating evidence through the graph (EP — Evidence Propagation).

Tortoise runs as a service — self-hosted or hosted — and your tools connect to it over MCP (Model Context Protocol). You don't import it into your application; you run it and point your agent at it, the way you'd run MongoDB and connect a driver.

A product of Premise Labs.

Quickstart — Install → Connect → Query

1. Install

Pick one:

⚠️ Embedded mode (plain docker run) is for evaluation only — it is not durable. For real data use docker compose or point the daemon at a FalkorDB with TORTOISE_DB_URI. See License & FAQ and docs/infra-runbook.md.

2. Connect

Point your agent at Tortoise over MCP:

# Hosted
claude mcp add tortoise https://api.premiselabs.co/mcp
# or self-hosted
claude mcp add tortoise http://localhost:8000/mcp

# Codex
codex mcp add tortoise http://localhost:8000/mcp --bearer-token-env-var TORTOISE_API_KEY

Or add to .mcp.json:

{
  "mcpServers": {
    "tortoise": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

3. Query

Your agent now has Tortoise's tools — create points, query the graph, check belief structure, run evidence propagation. See the MCP tool surface for the full registry (58 tools) and the REST reference (as it lands).

SDK for local dev / scripting

pip install tortoise-graph gives you the SDK — a driver for local development, scripting, and power-user access against a running daemon (or embedded mode for experiments). Tortoise is a service: the SDK connects, it doesn't replace the server. (The package is published as tortoise-graph on PyPI — the bare tortoise name is squatted by an unrelated library, #258.)

pip install tortoise-graph   # or: pip install 'tortoise-graph[embeddings]' for vector search
# from source: pip install -e .
python -m tortoise.selfhost # run the daemon locally (see env table below)

Self-host configuration

Also: tortoise-serve http [--host] [--port] [--api-key] (flags override env), and tortoise-serve (stdio MCP) for scripting.

License & FAQ

Tortoise is Business Source License 1.1 — see LICENSE and the license notes (clause-by-clause precedent + audit).

• Self-hosted: free production use for organizations under US $5,000,000 annual revenue (trailing 12 months); above that, a commercial license is required.
• Hosted (api.premiselabs.co): a separate commercial product with a free tier — not covered by the BSL grant.
• MIT products are never blocked: connect over MCP/REST and you never import Tortoise — the license boundary sits at the network, so your distribution stays clean.
• MPL 2.0 conversion: every version converts to Mozilla Public License 2.0 (file-level copyleft — enterprise-safe) four years after publication.
• Can't offer Tortoise as a service: the grant never permits reselling Tortoise (or a substantially similar product) to third parties as a hosted/managed service.

What's here

• tortoise/ — the SDK, MCP server, projection, search engine, backup/restore, and the self-host daemon (tortoise/selfhost.py)
• integrations/ — thin connectors that talk to Tortoise over MCP (not SDK imports)
• premise-labs/ — the hosted product's landing pages + dashboard (deploys to Cloudflare Pages)
• docs/ONTOLOGY.md — canonical ontology v3.1 (co-located with the code it governs)
• tests/ — test suite

Canonical ontology

docs/ONTOLOGY.md is the single source of truth for the entity model (Point, Subject, Object, Event, Source), edge topology (IMPL/NAND/structural/about*), kind vocabularies, and EP semantics. It is canonical — product gaps are filed as issues, never added to the ontology as roadmap detail.

Repo map & issue routing

File issues in the repo that owns the code:

Rule of thumb: if the issue is about Tortoise code (this repo's tortoise/ or premise-labs/ dirs), file it here. If it's about agent tooling, file in agent-infra. If it's about Premise Labs ops (meetings/CRM), file in premise-labs.