SciTrace

English · 中文

An MCP server that moves AI agents' reasoning chains out of the context window and into a database.

One line of MCP config. Two tools. The agent calls build_trace to record each reasoning step and query_trace to pull history back on demand. Data lives in SQLite, not in the context window.

🚀 See it in 30 seconds:

pip install scitrace
scitrace-demo --viz      # writes a perovskite research demo chain + renders the visualization

Open the generated scitrace-demo.html in a browser: hover nodes for summaries, click for the detail panel, double-click to collapse subtrees — find the purple dashed edge (backtrack), the most interesting moment of a reasoning chain.

---

Why not prompts or skills?

Prompts and skills can force an agent to emit structured reasoning, but they cannot do the following five things.

1. The context window is a scarce resource, not a warehouse

	Prompt-instructed output	SciTrace
Context after 10 steps	10 full JSON blocks (500–1500 tokens) stacked in the window	10 short call records; data lives in SQLite
After 50 steps	The agent starts "forgetting" earlier steps — the window fills with history	Context stays clean; query_trace fetches exactly what's needed
Across sessions	New session = everything lost	SQLite persists; new sessions query directly

With prompts, reasoning chains accumulate and steal token budget from the real task. SciTrace moves the data out — the context window is for thinking, SQLite is for storage.

2. Prompts only write; SciTrace can query

Prompt: "What was that earlier hypothesis again?" → agent rummages through 3000 tokens of chat history → maybe finds it, maybe not

SciTrace: query_trace(type="hypothesis") → exact result, no chat history involved.

Structured queries = type=backtrack finds every failed backtrack point, type=experiment lists all experiments, trace_id=xxx returns the full chain. Prompts cannot do this.

3. A DAG is not flat

Prompts force agents to output sequential lists. But scientific reasoning is not linear — it forks, backtracks, and has dependencies.

h1 (hypothesis) → a1 (analysis) → e1 (experiment) → b1 (backtrack) → e2 (revision) → v1 (verification) → c1 (conclusion)
                                          ↑
                                    parent_id declares the dependency explicitly

parent_id turns a flat list into a directed acyclic graph. This graph structure doesn't consume context — it lives in SQLite foreign-key relationships.

4. Write once, every agent can use it

	Prompt	Skill	SciTrace
Claude	One per agent	One per agent	✅ Same MCP config
Cursor	One per agent	—	✅ Same MCP config
Hermes	One per agent	One per agent	✅ Same MCP config
Codex	One per agent	—	✅ Same MCP config

MCP is a protocol standard. Write the server once and every MCP-compatible agent gets reasoning tracing automatically. No need to port prompts per agent.

5. Data can be consumed by programs

Structured output produced by prompts is readable only by an LLM. SciTrace's data lives in SQLite — any tool can read it:

Python analysis scripts → read SQLite directly
Visualization           → scitrace-viz renders an HTML report
CI/CD pipelines         → sqlite3 CLI queries
Jupyter                 → import sqlite3 and analyze

No LLM required — the consumer of the data can be code.

---

Architecture

Agent (Claude/Cursor/Hermes/Codex)
    │
    │ MCP protocol (stdio)
    │
    ▼
┌─────────────────────────┐
│   SciTrace MCP Server   │
│                         │
│  build_trace  ← writes  │
│  query_trace  ← reads   │
│                         │
│  ↓ SQLite               │
│  steps table            │
│  - id, parent_id (DAG)  │
│  - type (6 step types)  │
│  - summary, artifacts   │
└─────────────────────────┘

---

Quick start

pip install scitrace

Add to your MCP client config:

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace"]
    }
  }
}

The agent can now call build_trace and query_trace.

Storage

Item	Default	Override
Database path	~/.scitrace/traces.db	SCITRACE_DB env var, or --db <path> in MCP args
Visualization output dir	current working directory	SCITRACE_OUTPUT env var

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace", "--db", "/path/to/custom.db"]
    }
  }
}

Visualization

pip install ships a scitrace-viz command — it renders a reasoning chain as fully offline, interactive HTML (hand-drawn SVG DAG, zero external dependencies, works in air-gapped environments):

scitrace-viz                 # visualize the most recent trace
scitrace-viz <trace_id>      # visualize a specific trace
scitrace-viz --out ./viz     # specify the output directory
scitrace-viz --index         # generate an overview index.html for all traces
scitrace-viz --theme dark    # set the initial theme (switchable in-page)

• Hover a node for the full summary; click for a detail panel (parent/children, artifact file links)
• Double-click to collapse subtrees; wheel zoom, drag pan, one-click fit
• Light/dark theme toggle (remembered in localStorage); cyclic reasoning chains automatically fall back to a timeline layout
• Databases from v0.1.x are migrated automatically on first open; the original file is backed up as traces.db.bak-<date>

---

Make the agent actually record

Installing the MCP server is only the first step: agents won't call build_trace on their own until you tell them to in their config.

Canonical rules: prompts/RULES.md (when to record / what to record / when to query). Client templates are compressed; RULES wins on conflict.

Client	Template	Where to put it
Claude Desktop	prompts/claude-desktop.md	Project Instructions / CLAUDE.md
Cursor	prompts/cursor.md	.cursor/rules/scitrace.mdc
Codex CLI	prompts/codex-agents.md	AGENTS.md in the project root
Hermes	prompts/hermes.md	system prompt / skill

Hard-rule summary:

1. When to record: build_trace only after a verifiable subtask; dead ends must be backtrack; flush before session end
2. What to record: stable trace_id; one-line summary = action + result; parent_id builds the DAG
3. When to query: new session / resume from failure / early steps lost from context → query_trace first; never make the user re-explain what's already in the DB
4. Boundary: record and query only — do not control reasoning paths

---

The two tools

build_trace

Records a reasoning step. The agent calls it after each verifiable subtask.

Parameter	Description
step_id	Unique identifier for this step
trace_id	Which reasoning chain this step belongs to
type	hypothesis / analysis / experiment / verification / conclusion / backtrack
summary	One-line summary of what this step did
parent_id	Which step this depends on (builds the DAG)
artifacts	Associated file paths

query_trace

Queries historical reasoning steps.

Parameter	Description
trace_id	Filter by reasoning chain
type	Filter by step type
limit	Max steps returned (default 50, max 1000)

---

Example

A complete reasoning chain:

build_trace: { "step_id": "h1", "trace_id": "exp-001", "type": "hypothesis", "summary": "Assume P != NP" }
build_trace: { "step_id": "a1", "trace_id": "exp-001", "type": "analysis", "summary": "SAT is hard", "parent_id": "h1" }
build_trace: { "step_id": "e1", "trace_id": "exp-001", "type": "experiment", "summary": "Run benchmarks", "parent_id": "a1", "artifacts": ["results.csv"] }
build_trace: { "step_id": "c1", "trace_id": "exp-001", "type": "conclusion", "summary": "Conclusion: ...", "parent_id": "e1" }

query_trace: { "trace_id": "exp-001" }        → the full chain
query_trace: { "type": "experiment" }         → all experiment steps
query_trace: { "limit": 10 }                  → the 10 most recent steps

---

Development

git clone https://github.com/Mobai-read/scitrace
cd scitrace
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full contribution workflow.

---

Summary comparison

	Prompt	Skill	SciTrace
Data location	context window	context window	SQLite
Cross-session persistence	❌	❌	✅
Structured queries	❌	❌	✅
DAG dependencies	❌	❌	✅ (parent_id)
Program-readable	❌	❌	✅ (SQLite)
Multi-agent	one per agent	one per agent	✅ one config
Long reasoning chains	blows up the context	blows up the context	context stays clean

---

Documentation

• Changelog
• Security policy
• Contributing
• Development baseline PRD

---

Share / Cite

Spread the word — or embed SciTrace in your own project:

• GitHub: https://github.com/Mobai-read/scitrace
• PyPI: https://pypi.org/project/scitrace/

Add the badge to your README:

[![PyPI](https://img.shields.io/pypi/v/scitrace)](https://pypi.org/project/scitrace/)

Install it anywhere:

pip install scitrace

---

License

MIT