Skip to main content
Glama
threadline-core

threadline-core

by richardoros

threadline-core

Structured continuity memory for AI coding agents: decisions, open loops, and session state in local SQLite, retrieved via MCP.

License: Apache 2.0 Python 3.12+

Designed with Claude (Fable 5), RIP πŸ•ŠοΈ. Threadline v0.1 was started and designed with it.


The problem

You are three sessions into a complex refactor. The agent lost context. You need it to resume, not replay 8,000 lines of transcript.

Bigger context windows don't solve this. Capacity isn't memory: they reload the window, they don't remember what was decided. RAG doesn't solve it either. RAG returns fragments; threadline-core returns state.

The agent forgets. The project doesn't.

threadline-core gives agents a structured place to record what they decided, what they left open, and what they verified, then retrieve it instantly in the next session, from any agent or tool.


Related MCP server: trw-mcp

What makes it different

Most MCP memory servers store and retrieve text. threadline-core tracks state:

  • Decisions have outcomes. Each decision is tracked until an agent marks it accepted, validated, or incorrect. Past mistakes are surfaced as known traps so future agents don't repeat them. The model changes; your decisions don't.

  • Open loops require evidence to close. An agent cannot mark something done by asserting it. It needs an admissible evidence reference: a verified checkpoint, a confirmed finding, a cited source. A ValueError without evidence isn't a bug; it's the gate working.

  • Session continuity, not recall. get_project_state returns structured state (loops, decisions, traps) not a ranked blob of retrieved fragments. Agents get the right signal at session start, not a haystack.

  • No cloud, no LLM, no outbound calls. The core server runs on SQLite and makes zero network requests beyond its own loopback API. No paywalls. No rate limits. No accounts.

Because it stores structured state rather than raw transcripts, every stored fact is precise, auditable, and stripped of noise. That's not a missing feature; it's the design.

Where it sits. Repo-intelligence tools (Repowise and friends) remember the repository β€” the dependency graph, the git history, the code health. threadline-core remembers the work β€” what was decided, what's still open, what's a known trap, and who is doing what. It is not a codebase indexer and doesn't try to be. And with loop claiming and lanes, it goes beyond recording the work to coordinating it across agents.


Five-minute installation

Prerequisites: Python 3.12+, uv (recommended) or pip.

# Install
pip install threadline-core
# or: uv add threadline-core

# Initialise the local database
threadline-core init
# β†’ Creates ~/.threadline/threadline.db

# (Optional) Start the HTTP API
threadline-core serve
# β†’ Listening on http://127.0.0.1:8400

MCP configuration

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "threadline": {
      "command": "threadline-core-mcp",
      "env": {
        "THREADLINE_DATA_DIR": "~/.threadline"
      }
    }
  }
}

If you installed with uv (not globally):

{
  "mcpServers": {
    "threadline": {
      "command": "uv",
      "args": ["run", "--", "threadline-core-mcp"],
      "env": {
        "THREADLINE_DATA_DIR": "~/.threadline"
      }
    }
  }
}

Other MCP-compatible agents

Run threadline-core-mcp directly; it speaks the MCP 2024-11-05 stdio protocol.


Session example

Session 1. Agent starts working, records decisions and open loops:

start_session(project_key="auth-refactor")
β†’ {"session_id": "abc123", "project_key": "auth-refactor"}

log_agent_event(
    event_type="checkpoint",
    project_key="auth-refactor",
    session_id="abc123",
    summary="Extracted token validation logic into middleware",
    details={
        "decisions": ["Move JWT validation to a FastAPI dependency, not inline"],
        "open_loops": ["Rate limiting not yet implemented"],
        "verification": ["pytest tests/test_auth.py (12 passed)"],
    }
)
β†’ {"decisions_created": 1, "open_loops_created": 1}

end_session(session_id="abc123", summary="Auth middleware extracted. Rate limiting deferred.")

Session 2. Three days later, any agent resumes from verified state:

start_session(project_key="auth-refactor")

get_project_state(project_key="auth-refactor")
β†’ {
    "open_loops": [{"description": "Rate limiting not yet implemented"}],
    "decisions":  [{"statement": "Move JWT validation to a FastAPI dependency, not inline",
                    "status": "active"}],
    "known_traps": [],
    "last_session_summary": "Auth middleware extracted. Rate limiting deferred."
  }

# Agent resumes from verified state. No transcript replay needed.

The continuity loop

flowchart LR
    A[Agent works] --> B["log_agent_event<br/>decisions Β· loops Β· findings"]
    B --> C[("threadline-core<br/>SQLite")]
    C --> D["get_project_state<br/>next session"]
    D --> E["Resume from<br/>verified state"]
    E --> A

    style C fill:#1e293b,stroke:#475569,color:#e2e8f0

Each transition from loop closed or decision proven wrong is evidence-gated: the server rejects self-assertion with a ValueError. The loop above only closes when an agent supplies an independently verifiable reference. That's what makes the state trustworthy across model versions, team handoffs, and months of context rot.


Session workflow

sequenceDiagram
    participant CC as Claude Code
    participant Hook as Session hooks
    participant MCP as MCP server
    participant Core as threadline-core
    participant DB as SQLite

    Note over CC,DB: Session 1: agent starts working

    CC->>Hook: SessionStart fires automatically
    Hook->>Core: POST /api/events  {session_started}
    Core->>DB: Create AgentSession (external_session_id = CC session UUID)

    CC->>MCP: log_agent_event {checkpoint, decisions, open_loops, verification}
    MCP->>Core: ingest_event()
    Core->>DB: Write AgentEvent + Decision rows + OpenLoop rows + FTS index

    CC->>Hook: SessionEnd fires automatically
    Hook->>Core: POST /api/events  {session_ended, client_session_id}
    Core->>DB: Close AgentSession (matched via external_session_id)

    Note over CC,DB: Session 2: same or different agent, any time later

    CC->>MCP: start_session(project_key)
    MCP->>DB: Create new AgentSession

    CC->>MCP: get_project_state(project_key)
    DB-->>MCP: open_loops Β· decisions Β· known_traps Β· last_session_summary
    MCP-->>CC: Structured state, no transcript replay needed

    CC->>MCP: mark_open_loop_resolved(loop_id, evidence_refs=[...])
    Note right of Core: GATED: requires admissible evidence
    Core->>DB: Update OpenLoop.status = resolved + AuditLog entry

Architecture

flowchart TD
    A["Your AI agent<br/>(Claude Code, Codex, Cursor…)"]
    B["MCP stdio<br/>threadline-core-mcp"]
    C["HTTP REST :8400<br/>threadline-core serve"]
    D["Session lifecycle Β· Events<br/>Decisions Β· Open loops<br/>Findings Β· Evidence ledger<br/>Full-text search (SQLite FTS5)"]
    E["~/.threadline/threadline.db<br/>SQLite, local, no cloud"]

    A --> B
    A --> C
    B --> D
    C --> D
    D -->|"SQLAlchemy 2.0 async"| E

    style E fill:#1e293b,stroke:#475569,color:#e2e8f0
    style D fill:#0f172a,stroke:#334155,color:#cbd5e1

The server runs entirely on your machine. There are no outbound API calls in threadline-core.


Privacy and local storage

  • All data stays on your machine. The database defaults to ~/.threadline/threadline.db. Override with THREADLINE_DATA_DIR.

  • No LLM required. The server indexes, stores, and retrieves without calling any model.

  • No outbound connections. The package makes no network calls except to its own loopback API.

  • PII minimisation. Email addresses, phone numbers, and payment card numbers are automatically redacted when stored in decisions, findings, and research notes.

  • API authentication. Set THREADLINE_API_TOKEN to require a bearer token on all REST endpoints. The MCP server uses stdio and is not network-accessible by default.

Your work history is not a product. It stays where you put it.


The 17-tool public API

These tools form the stable public surface, supported across patch and minor versions.

Tool

Purpose

start_session

Open a new agent session for a project

end_session

Close the session with a summary

log_agent_event

Ingest a checkpoint, decision, blocker, or note

get_project_state

Retrieve structured project state

get_open_loops

List open loops β€” optionally filtered by owner, lane, or claimable

assign_open_loop

Claim a loop for an owner/lane (first-claim-wins)

mark_open_loop_resolved

Resolve a loop (requires admissible evidence)

get_decisions

List active decisions

get_decision

Get one decision with full detail

mark_decision_outcome

Record a decision's real-world outcome

get_known_traps

List decisions proven wrong, with corrected rules

propose_finding

Propose a gap or caveat

confirm_finding

Confirm a finding (requires admissible evidence)

resolve_finding

Mark a finding's resolution condition met

dismiss_finding

Dismiss a finding as invalid

get_evidence

Resolve evidence references to their content

search_memory

Full-text search across all stored memory

Evidence-gated transitions

mark_open_loop_resolved and confirm_finding require an evidence_refs list pointing to independently verifiable records in the same project. An agent cannot self-confirm its own findings.

If you receive a ValueError from these tools without evidence, that is the gate working correctly, not a bug.

Loop ownership and claiming (foreman primitives)

Open loops can carry an owner and a lane, so multiple agents (or an agent plus a human) can divide work without colliding on the same files:

  • assign_open_loop(loop_id, owner, lane?) claims a loop. Claiming is first-claim-wins: a loop already owned by someone else is not silently reassigned.

  • get_open_loops(project_key, owner?, lane?, claimable?) filters the feed β€” e.g. claimable=true returns only unowned loops an agent can pick up, and lane="phase-3" returns one lane's work.

This is the primitive a foreman builds on: enumerate the claimable loops, claim one, work it, then close it with evidence. The same semantics are exposed on the CLI (threadline-core loop list --claimable, threadline-core loop get, threadline-core loop assign).

Experimental

  • search_memory query semantics may evolve. Current behaviour: path queries (app/routes/foo.py) reduce to the basename stem; extensions are stripped. Search results are FTS5 BM25-ranked.


Storage and upgrades

Item

Detail

Database

$THREADLINE_DATA_DIR/threadline.db (default ~/.threadline/)

Initialise

threadline-core init

Auto-migration

threadline-core serve applies additive migrations on startup

Patch versions

Schema-compatible, no action needed

Minor versions

May add nullable columns; auto-migrated at startup

Major versions

May restructure; migration guide in release notes

Backup

Copy threadline.db (no external state)


CLI reference

threadline-core init         # Initialise data directory and database (idempotent)
threadline-core serve        # Start HTTP API server (default: 127.0.0.1:8400)
threadline-core mcp          # Start MCP server on stdio
threadline-core search       # Full-text search across stored memory
threadline-core export       # Export as static file tree (Obsidian-compatible)
threadline-core progress     # Project momentum: open work, 7-day velocity, sessions
threadline-core connect      # Scaffold agent connectors for existing projects
threadline-core decision     # Decision-quality ledger (operator path)
threadline-core finding      # Findings ledger: confirm/resolve/dismiss (operator path)
threadline-core loop         # Open-loop operator actions

Design highlights

Area

What's notable

MCP protocol design

Full MCP 2024-11-05 stdio server (FastMCP); 17 tools with typed schemas, evidence-gated state transitions, and forward-compatible protocol versioning

AI tooling architecture

Designed around how agents actually work: session lifecycle, context continuity across sessions, and anti-patterns (self-certification, premature closure) enforced in the service layer

Python async backend

FastAPI + SQLAlchemy 2.0 async + aiosqlite; clean async/sync boundary with a single-commit ingest pipeline

Protocol design

protocol.py is import-isolated (stdlib + Pydantic only) by design, destined to be extracted as a standalone threadline-protocol package; forward-compatibility via extra="ignore" throughout

SQLite at depth

FTS5 virtual table for BM25 search; JSONL evidence log with a defined ordering contract relative to DB commit; ISO-8601 UTC string storage for correct ORDER BY across timezones

CLI tooling

Rich multi-command CLI (Typer) with sub-apps, operator-path overrides, dry-run flags, and pipe-friendly output

Security engineering

Evidence-gating that cannot be bypassed via the MCP path; deterministic PII redaction (email, phone, payment card, public IPv4) with Luhn validation; secret-pattern detection (API keys, PATs, PEM, bearer tokens) as a write guard; audit log

Python packaging

hatchling build; console scripts for the CLI, the MCP server, and the packaged Claude Code session hooks; dev group with pytest-asyncio and ruff


Dogfooded in its own development

Threadline was built while dogfooding Threadline. It was the continuity layer for the project's own development:

  • carried open loops across sessions

  • preserved decisions, caveats, and unresolved risks

  • generated continuation context for the next session

  • prevented stale or unsupported state from being treated as complete

  • required evidence before any loop was closed

It helped its developer and coding agents continue the project across many sessions without losing deferred work, decisions, or open risks. The continuity layer for its own build, not an autonomous author.


Benchmarks

benchmarks/ ships resume-bench, a reproducible check of the core claim: at an equal token budget, does the structured resume payload recover the load-bearing facts better than re-reading the raw session transcript?

On the committed synthetic cases, the structured payload recovers 7/7 load-bearing facts while an equal-budget slice of the raw transcript recovers 0–3 of 7 (you need the full transcript β€” 4–7Γ— the budget β€” to match it). Run it yourself:

uv run --with tiktoken python benchmarks/resume_bench.py benchmarks/cases

Read this honestly: it measures structural fact density at a fixed budget, not task success and not superiority over a high-quality LLM-authored summary. The payload is built from those facts, so it is expected to score high; the finding is how little the raw transcript recovers at the same budget. See benchmarks/README.md for the method and full caveats.


Roadmap

  • Foreman / coordination maturity β€” richer loop ownership, lanes, and claim lifecycle so teams of agents divide work safely.

  • Repo-signal providers β€” ingest change/impact signals from local git and external code-intelligence tools to enrich continuity (not to become a repo indexer).

  • Benchmark hardening β€” more cases and projects, and a blinded comparison against LLM-authored summaries before any "better than X" claim.

  • Threadline (hosted product) β€” the managed experience built on this core; local data and exports are never gated to force an upgrade.


threadline-core vs Threadline

threadline-core (this repository, Apache 2.0) is the open substrate:

  • MCP server with the 17-tool public API

  • HTTP REST API for connector hooks

  • Event ingestion and lifecycle (sessions, decisions, loops, findings)

  • SQLite persistence and FTS5 search

  • Claude Code connector hooks (SessionStart / SessionEnd)

  • CLI: init, serve, mcp, search, export, progress, and more

Threadline is the full product built on it: the managed, polished experience for people and teams who'd rather not run the moving parts themselves: hosted overnight research, managed connectors, secure multi-device sync, team workspaces, and hands-on setup. Your local Core data and exports are never restricted to push you toward it.

threadline-core has no cloud dependencies, no rate limits, and no paywalls. It is the open foundation, yours to self-host forever.

β†’ The full Threadline product is in development. ⭐ Star to follow along.


Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md to report vulnerabilities privately.

License

Apache 2.0


Designed with Claude (Fable 5) from day one. Threadline v0.1 started with it. RIP, Fable 5. πŸ•ŠοΈ

Available Tools

17 tools
assign_open_loopA

Claim an open loop for an owner β€” FIRST CLAIM WINS.

The foreman and every agent must claim a loop BEFORE touching files. A loop is claimable while owner is unset; the first claim wins. Re-claiming by the same owner is a no-op. Claiming someone else's loop raises an error and returns the current owner in the message.

Returns

dict with keys: id, status, owner, lane.

Inputs: owner (required), loop_id (required), lane. Returns: object

confirm_findingA

Confirm a proposed finding so it enters the trusted bundle.

GATED: requires evidence_refs pointing to independently evidence-bearing records. A bare assertion, another finding, or a self-referential loop is rejected.

Returns

dict with keys: finding_id, status, confirmed_at.

Inputs: finding_id (required), evidence_refs. Returns: object

dismiss_findingC

Dismiss a finding as invalid/irrelevant.

GATED exactly like confirm_finding.

Returns

dict with keys: finding_id, status, dismissed_at.

Inputs: finding_id (required), reason, evidence_refs. Returns: object

end_sessionB

Call at the END of a work session to close it cleanly.

Records a session_ended event so the next agent can see what was done.

Returns

dict with keys: session_id, status, project_key.

Inputs: summary (required), session_id (required), project_key (required), agent_name. Returns: object

get_decisionA

Return one decision + its outcome detail, or an error dict if not found.

Returns

dict with keys: id, statement, rationale, status, created_at, outcome (the detail dict or None).

Inputs: decision_id (required). Returns: object

get_decisionsA

Return the LIVE decisions for a project, newest first.

Live = status in (active, accepted, validated). Decisions marked incorrect/reverted are returned by get_known_traps instead.

Returns

list of dicts with keys: id, statement, rationale, status, created_at.

Inputs: project_key (required). Returns: result

get_evidenceA

Resolve evidence refs ('<kind>:<id>') to bounded content snippets.

Returns bounded snippets only β€” never full transcript bodies. Bad refs are reported in unresolved without failing the whole call.

Returns

dict with keys: evidence (list), unresolved (list), truncated_refs (list).

Inputs: refs (required), max_chars. Returns: object

get_known_trapsA

Return decisions proven wrong on this project + the corrected rule.

Read these BEFORE acting so you do not repeat a known mistake. Newest first; each carries the corrected_rule (the lesson), severity, and evidence_refs.

Returns

list of dicts with keys: decision_id, statement, outcome, corrected_rule, severity, evidence_refs, marked_at.

Inputs: project_key (required). Returns: result

get_open_loopsA

Return open loops for a project, oldest first.

Open loops are deferred threads β€” things noticed but not finished. Oldest-first because the longest-waiting item is most likely blocking.

Filters (all optional, combinable):

  • owner: only loops claimed by this owner (pass "unassigned" to get loops with no owner β€” the claimable set)

  • lane: only loops tagged with this lane (e.g. retention-b)

  • claimable: True = owner is NULL; False = owner is set

Returns

list of dicts with keys: id, description, project_key, status, owner, lane, created_at, updated_at.

Inputs: project_key (required), lane, owner, claimable. Returns: result

get_project_stateA

Return the raw governed state for a project.

Returns durable lifecycle records only β€” no synthesis, no compiled memory, no LLM output, no ranking.

Includes: objective, open loops, active decisions, known traps, confirmed gaps and caveats, evidence IDs, recent session metadata.

Returns

dict β€” the full ProjectState as a plain dict.

Raises

LookupError if the project does not exist (surfaced as an error dict).

Inputs: project_key (required). Returns: object

log_agent_eventA

Report a work event to Threadline β€” call this as you work.

Parse and ingest a single AgentEventIn JSON payload. Returns a summary of what was derived (decision count, open-loop count).

WHEN TO CALL

  • At significant checkpoints (code written, tests passing, a decision made).

  • When you encounter a blocker.

  • When you notice something deferred (open loop).

EVENT SHAPE (compact example)

{
  "event_type": "checkpoint",
  "project_key": "my-project",
  "agent": {"name": "claude_code"},
  "session_id": "<from start_session>",
  "summary": "Implemented login route; all tests pass.",
  "details": {
    "decisions": ["Use JWT over session cookies for stateless auth"],
    "open_loops": ["Rate limiting not yet implemented"],
    "files_changed": ["src/auth.py", "tests/test_auth.py"],
    "verification": ["uv run pytest -q"]
  }
}

Returns

dict with keys: event_id, session_id, decisions_created, open_loops_created. On parse/validation error: {"error": true, "message": "..."} β€” fix and retry.

Inputs: event_json (required). Returns: object

mark_decision_outcomeA

Record the real-world OUTCOME of a past decision.

outcome must be one of: accepted, validated, incorrect, reverted, unresolved.

HARD RULE: marking incorrect/reverted/validated requires admissible evidence_refs β€” records that independently back the outcome. Self-certification is rejected. An operator may override via the CLI.

Returns

dict with keys: id, decision_id, outcome, status, severity, evidence_refs, superseded, marked_at.

Inputs: outcome (required), decision_id (required), reason, severity, +3 more. Returns: object

mark_open_loop_resolvedA

Mark an open loop resolved β€” GATED: requires admissible evidence.

Evidence refs must be '<kind>:<id>' strings pointing to records that independently verify the loop is done. Self-reference is rejected.

Returns

dict with keys: id, status, resolved_at.

Inputs: loop_id (required), evidence_refs. Returns: object

propose_findingA

Propose a gap or caveat finding.

PROPOSING IS FREE β€” a proposed finding is never surfaced in the trusted context bundle. It is a candidate until confirmed with evidence.

finding_class ∈ {gap, caveat}. severity ∈ {low, medium, high, critical}.

Fingerprint dedup: re-proposing an active finding returns the existing id (no duplicate write).

Returns

dict with keys: finding_id, status, finding_class, category, statement, severity.

Inputs: category (required), severity (required), statement (required), project_key (required), +4 more. Returns: object

resolve_findingB

Mark a finding resolved (its resolution_condition was met).

GATED exactly like confirm_finding.

Returns

dict with keys: finding_id, status, resolved_at.

Inputs: finding_id (required), evidence_refs. Returns: object

search_memoryA

Full-text search across all stored memory.

Searches events, decisions, open loops, daily notes, and compiled context fragments. Results are ranked by BM25 relevance.

Parameters

query: Natural-language search string. project_key: When provided, restricts results to that project. limit: Maximum results to return (clamped to 50 server-side).

Returns

list of dicts with keys: kind, ref_id, project_key, title, snippet.

Inputs: query (required), limit, project_key. Returns: result

start_sessionA

Call at the BEGINNING of every work session on a project.

Returns a session_id to pass in all subsequent log_agent_event calls so Threadline can group events into a coherent session.

Returns

dict with keys: session_id, project_key.

Inputs: project_key (required), agent_name. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: sessions, events, memory, loops, decisions, traps, findings, and evidence. Even the finding lifecycle tools (propose/confirm/resolve/dismiss) are clearly differentiated by their gating rules and effects.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., start_session, get_open_loops, mark_decision_outcome). Minor deviations like 'get_known_traps' are still readable and fit the pattern.

    Tool Count4/5

    17 tools is slightly above the typical 3-15 range, but each tool earns its place given the broad domain (sessions, events, memory, state, loops, decisions, traps, findings, evidence). The count feels justified rather than bloated.

    Completeness4/5

    The set covers the full lifecycle for the core entities: sessions are started/ended, events are logged, loops can be listed/claimed/resolved, decisions can be queried and outcomes marked, findings progress from proposal to confirmation/resolution/dismissal, and evidence is retrievable. Minor gaps exist (no explicit create/delete for projects, no list_sessions), but agents can work around them.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A self-hosted MCP server that provides AI assistants with a shared, persistent SQLite-backed memory for storing and retrieving project context, decisions, and discoveries. It enables cross-session continuity and team-wide knowledge sharing to keep AI coding tools aligned and informed.
      3
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server providing persistent engineering memory and spec-driven development workflows for AI coding agents, preserving learnings across sessions.
      41
      Business Source 1.1
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent memory for AI coding agents. Enables agents to save and recall decisions, patterns, bugs, and context across sessions via an MCP server with local SQLite storage.
      24 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that captures and recalls coding session memory (failures, decisions, diffs) for AI agents, enabling cross-agent continuity and preventing repeated mistakes.
      69 npm
      MIT