Tortoise boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

This run examines Tortoise as a graph-memory service for agents, including its shipped capture, extraction, persistence, retrieval and context-delivery consumers. Its intended use is to characterize how retained information reaches later model work, not to review an enclosing general-purpose agent runtime. The target class is memory/knowledge/context-engineering system. The boundary kind is complete artifact, partial loop: the complete repository is frozen and eligible evidence, but this initial inspection has not established coverage of every shipped state-producing, maintenance, admission and consumption path. This is an inspection limit, not a missing checkout or an assertion that those paths are external.

The frozen revision is 54922a800f96858935b58ef250da569a4896df44 in SRC-1. The checkout's HEAD was checked against that pin. The applicability cutoff is 2026-10-30; later revisions, live hosted deployments and linked external documents are not evidence in this run. The overall tier is code-grounded: source code establishes entry-point dispatch, the model-dependent extraction seam and the retrieval-to-context call. No target code, tests, examples, model calls or services were executed.

Classification and initial trace

Tortoise qualifies even though its read-time reflex need not call a generative model. The shipped session-capture path dispatches to model-dependent extraction; the resulting graph is available to later context delivery. The package is not merely an isolated graph library: its console scripts dispatch into a stdio MCP server or an HTTP daemon, and the repository also ships client and harness-facing code. These findings are based on SRC-1, pyproject.toml, tortoise/deployment.py, tortoise/mcp_server.py, tortoise/sdk.py and tortoise/extractor_v2.py.

The declared service orientation is explicit:

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. --- README.md

The executable entry point selects the shipped daemon rather than treating it as an external application:

if sys.argv[1:2] == ["http"]: sys.argv.pop(1) serve_http() return from tortoise.mcp_server import main main() --- tortoise/deployment.py

Initial tracing established these connections, without claiming exhaustive branch coverage:

• Entry points and backing state. pyproject.toml declares tortoise, tortoise-ingest and tortoise-serve. tortoise/deployment.py selects stdio or HTTP. tortoise/mcp_server.py resolves a backend URI, opens a Falkor projection and binds it to TortoiseSDK. The main CLI also dispatches to a shipped store-sync recovery command. These are source-level observations, not evidence of a running deployment (SRC-1, tortoise/__main__.py, tortoise/ingest.py).
• Model-dependent write path. capture_session selects an extraction lane, including _extract_session_v2. That method selects an adapter, bounds/redacts the conversation and invokes extract_session_v2; the extractor's completion helper calls the model. Thus this target serves model-dependent memory formation, not just a returning deterministic database query (SRC-1, tortoise/sdk.py, tortoise/extractor_v2.py).
• Persistence interfaces. _emit_event declares separate JSONL rebuild-journal, graph-event and optional Postgres-record outcomes. record_writer.py describes the record-write seam and its configuration gate. This establishes material storage surfaces requiring analysis, not an all-writes durability guarantee (SRC-1, tortoise/sdk.py, tortoise/record_writer.py).
• Later consumption. volunteer_context validates inputs, obtains the projection and calls run_volunteer_pipeline with the SDK's retrieval function. framework.py supplies adapters that put the returned block into framework prompts. The shipped Claude instructions tell the consuming agent to use injected prior memory and contribute durable information back. These consumers remain inside the target's functional scope (SRC-1, tortoise/sdk.py, tortoise/volunteer.py, tortoise/framework.py, tortoise/claude-hooks/CLAUDE.tortoise.md).
• Distinct hosted capture. Searches identify the hosted _capture_session_impl and the MCP wrapper importing it, as well as hosted and self-hosted volunteering endpoints. The hosted capture path is not assumed identical to sdk.capture_session merely because they have related responsibilities (SRC-1, tortoise/hosted_api.py, tortoise/mcp_server.py, tortoise/selfhost_api.py).

The model dependency is supported by the executable completion seam:

def _body(): kwargs = _cap_kwargs(model, max_tokens, stats) box["resp"] = model.complete(system=system, user=user, **kwargs) --- tortoise/extractor_v2.py

The read-to-context seam is also executable:

proj = self._get_proj() return run_volunteer_pipeline( proj, window, session_id=session_id, prior_context=prior_context, min_confidence=min_confidence, max_pointers=max_pointers, why=why, _search_fn=self.tortoise_fts_query, ) --- tortoise/sdk.py

Functional scope and inspection frontier

All tracked paths at the pin remain available under SRC-1. The table distinguishes initial inspection from material not yet inspected; it is not a whole-system coverage claim or a path allowlist.

No material shipped responsibility is deliberately excluded as an unrelated enclosing application. Conversely, external host runtimes (Claude Code, Codex, Cursor, Pi, Hermes, OpenClaw and framework engines), model-provider implementations, FalkorDB/Redis implementations, Postgres/Supabase service internals, cloud infrastructure and the live hosted installation are outside the frozen repository evidence. Their interfaces may be analyzed where represented in SRC-1; their internal scheduling, actual availability, provider quality, persistence guarantees and end-user outcomes cannot be established here. These are evidence-boundary exclusions, not responsibilities attributed to Tortoise (SRC-1, README.md, pyproject.toml, tortoise/framework.py, tortoise/record_writer.py).

No repository access gap was encountered. Available but uninspected paths above are an inspection frontier, not unavailable evidence. The partial-loop classification prevents treating this boundary declaration as proof of whole-system coverage. Later source inspection at this same pin may establish additional mechanisms, but cannot establish observed operation merely by finding their code.

Source register