threadline-core
This server provides structured continuity memory for AI coding agents: it records sessions, decisions, open loops, findings, and evidence in local SQLite and retrieves them over MCP/HTTP.
Start and end work sessions for a project.
Log agent events (checkpoints, blockers, notes) with decisions, open loops, files changed, and verification.
Retrieve a full project state: open loops, active decisions, known traps, confirmed findings, and last session summary.
List/filter open loops by owner, lane, or claimable status, and claim loops first-claim-wins.
Mark open loops resolved only with admissible evidence refs (evidence-gated).
Manage decisions: list/get live decisions, record outcomes (accepted, validated, incorrect, reverted, unresolved), with evidence required for non-self-certified outcomes.
Get known traps: decisions proven wrong, with corrected rules and severity.
Propose, confirm, resolve, or dismiss findings (gaps/caveats), with evidence gating for confirm/resolve/dismiss.
Resolve evidence references to bounded content snippets.
Full-text search across all stored memory with BM25 ranking, optionally filtered by project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@threadline-core get project state for auth-refactor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
threadline-core
Structured continuity memory for AI coding agents: decisions, open loops, and session state in local SQLite, retrieved via MCP.
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, orincorrect. 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
ValueErrorwithout evidence isn't a bug; it's the gate working.Session continuity, not recall.
get_project_statereturns 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:8400MCP 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:#e2e8f0Each 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 entryArchitecture
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:#cbd5e1The 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 withTHREADLINE_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_TOKENto 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 |
| Open a new agent session for a project |
| Close the session with a summary |
| Ingest a checkpoint, decision, blocker, or note |
| Retrieve structured project state |
| List open loops β optionally filtered by |
| Claim a loop for an owner/lane (first-claim-wins) |
| Resolve a loop (requires admissible evidence) |
| List active decisions |
| Get one decision with full detail |
| Record a decision's real-world outcome |
| List decisions proven wrong, with corrected rules |
| Propose a gap or caveat |
| Confirm a finding (requires admissible evidence) |
| Mark a finding's resolution condition met |
| Dismiss a finding as invalid |
| Resolve evidence references to their content |
| 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=truereturns only unowned loops an agent can pick up, andlane="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_memoryquery 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 |
|
Initialise |
|
Auto-migration |
|
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 |
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 actionsDesign 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 |
|
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 |
|
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/casesRead 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
Designed with Claude (Fable 5) from day one. Threadline v0.1 started with it. RIP, Fable 5. ποΈ
Available Tools
17 toolsassign_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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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.3MIT
- AlicenseBqualityBmaintenanceMCP server providing persistent engineering memory and spec-driven development workflows for AI coding agents, preserving learnings across sessions.41Business Source 1.1
- AlicenseNot gradedqualityDmaintenancePersistent 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 npm2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that captures and recalls coding session memory (failures, decisions, diffs) for AI agents, enabling cross-agent continuity and preventing repeated mistakes.69 npmMIT