Threadline

A file-backed continuity and control-state layer for the AI agents you already use.

简体中文 · Architecture · Security boundaries

Threadline helps a long-running, multi-project agent workspace recover the minimum context needed now without treating chat history, summaries, or hidden memory as the source of truth. It reads explicit workspace files, validates their contracts, produces a compact startup projection, and points to exact records when deeper evidence is required.

Threadline is a reference implementation, not an Agent framework. It does not choose a model, invent team personas, run your development lifecycle, or replace your existing coding assistant.

Why Threadline

As an agent workspace grows, useful operating state becomes scattered across project status files, task handoffs, dispatch records, and knowledge-return receipts. Loading everything on every new session is expensive and noisy. Loading only a hand-written summary is cheaper, but it can silently omit the one pending operation that matters.

Threadline uses a different boundary:

1. Files remain authoritative. Project state and ledgers stay inspectable and versionable.
2. The startup projection is disposable. It is generated live and is never a second source of truth.
3. Expansion is targeted. A pending or malformed record names the exact ID and file that must be inspected.
4. Failure is visible. Invalid JSON or a broken minimum contract stops projection generation instead of producing a reassuring partial view.
5. Scopes stay explicit. A registered project declares what the controller is allowed to read.

60-second demo

Prerequisite: a current Node.js LTS release.

git clone https://github.com/Ea12421/threadline.git
cd threadline

# Clean startup: compact projection, no escalation required
npm run demo:clean

# One active dispatch: projection identifies the exact record to inspect
npm run demo:pending

# A completed, content-addressed knowledge return
npm run demo:return

# Contract and behavior tests
npm test

# Repository validation and pre-release privacy scan
npm run validate
npm run release:scan

Every demo uses synthetic projects, IDs, timestamps, paths, and content. No personal workspace data is included.

The underlying CLI is intentionally small:

node scripts/build-startup-context.mjs \
  --workspace examples/demo-workspace \
  --scenario clean \
  --format markdown

Available demo scenarios are clean, pending, and return; output formats are markdown and json.

How it works

flowchart LR
    U["Human"] --> C["Control agent"]
    C --> P["Startup projection"]
    P --> S["File-backed control state"]
    S --> R["Project registry"]
    S --> A["Current-agent registry"]
    S --> D["Dispatch ledger"]
    S --> K["Knowledge-return ledger"]

    C -->|"scoped request"| W["Project agent"]
    W -->|"candidate package"| Q["Knowledge steward"]
    Q -->|"receipt"| D

    P -->|"clean"| M["Load minimum context"]
    P -->|"escalation + exact ID"| E["Read targeted evidence"]

Loading

At startup, Threadline reads the configured control-state files. It emits:

• source-relative-path inventory;
• current agent identities;
• registered projects and allowed read scopes;
• dispatch and return counts;
• every nonterminal dispatch ID and its targeted file;
• input/output character metrics;
• an explicit escalation.required decision with targeted reads.

Large request bodies, authorization text, receipts, knowledge content, chat transcripts, media URLs, and secrets are deliberately excluded from the projection.

Core contracts

The public example workspace uses four small contracts:

• Project registry — projects[id, name, status, allowedReadScope, stateFile]
• Current agents — agents[role, agentId, status, projectPath]
• Dispatch ledger — records[dispatchId, status, targetAgentId, requestKey, summaryHash]
• Return ledger — records[candidateId, sourceFingerprint, contentHash, sourceVersion, destination, processedAt]

A knowledge-return candidate may additionally carry sourcePointer, claims, evidence, privacyLevel, and suggestedDestination. Candidate bodies are routed as separate artifacts; they are not copied into the compact startup projection.

See data contracts and the dispatch and return protocol.

What Threadline is

• A local, file-backed continuity layer for long-lived agent workspaces.
• A compact control-state hydration mechanism.
• An auditable registry and ledger pattern.
• A fail-visible example of progressive context disclosure.
• A protocol boundary between a controller, project agents, and a knowledge steward.

What Threadline is not

• An autonomous multi-agent runtime or scheduler.
• A coding methodology, SDD framework, or persona library.
• A semantic-memory, RAG, vector database, or knowledge graph.
• A secret manager, sandbox, authorization server, or backup system.
• A guarantee that an agent will be correct.
• A daemon, dashboard, hosted service, or account integration.

Safety model

Threadline minimizes exposure; it does not make sensitive data safe to publish. Real ledgers may still contain private paths, identifiers, or operational metadata. Keep real workspaces private.

Before publishing a derivative repository:

1. build it in a new clean-room directory with new Git history;
2. use only synthetic fixtures;
3. scan tracked files and history for paths, credentials, emails, IDs, and private content;
4. run npm run release:scan and inspect the staged diff;
5. publish to a private staging repository first.

Read the full security boundaries.

Relationship to adjacent projects

Threadline is designed to compose with, not replace, existing tools:

• Superpowers provides composable coding skills and a software-development methodology. Threadline restores and routes control state around whichever skills a worker uses.
• BMAD Method provides role-oriented, scale-adaptive development workflows. Threadline does not model teams or lifecycle phases.
• OpenSpec keeps project change proposals and specification deltas reviewable. A Threadline project entry can point an agent to the relevant OpenSpec artifacts.
• Basic Memory provides persistent Markdown knowledge, semantic discovery, and MCP access. Threadline intentionally limits itself to explicit control records and bounded knowledge handoffs.

See the neutral comparison for more detail.

Current limitations

• The reference implementation uses a deliberately small, opinionated file contract.
• It does not watch files or refresh itself in the background.
• It does not send tasks to an agent platform; dispatch records describe and audit that boundary.
• It does not verify whether a target agent actually performed the requested work.
• Character-count metrics describe representation size; they do not prove completeness, truth, or API-token savings.
• Character-count reductions in the demo are not equivalent to API-token or subscription-quota savings.
• Adapting Threadline to another workspace still requires mapping that workspace's state files and permission model.

Repository map

scripts/       zero-dependency projection and validation utilities
tests/         behavior and leakage tests
schemas/       machine-readable public data contracts
examples/      synthetic demo workspace and scenarios
docs/          architecture, protocols, boundaries, and comparisons

License

Threadline is released under the MIT License.