Metadata-Version: 2.4
Name: scitrace
Version: 0.2.0
Summary: MCP server for AI agents to record and query their reasoning steps. SQLite-backed, zero-dependency beyond mcp SDK.
Author-email: Mobai-read <201200925+Mobai-read@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Mobai-read/scitrace
Project-URL: Repository, https://github.com/Mobai-read/scitrace
Project-URL: Issues, https://github.com/Mobai-read/scitrace/issues
Project-URL: Changelog, https://github.com/Mobai-read/scitrace/blob/main/CHANGELOG.md
Keywords: mcp,agent,trace,reasoning,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Dynamic: license-file

# SciTrace

[![PyPI](https://img.shields.io/pypi/v/scitrace)](https://pypi.org/project/scitrace/)
[![Python](https://img.shields.io/pypi/pyversions/scitrace)](https://pypi.org/project/scitrace/)
[![License](https://img.shields.io/pypi/l/scitrace)](LICENSE)
[![CI](https://github.com/Mobai-read/scitrace/actions/workflows/ci.yml/badge.svg)](https://github.com/Mobai-read/scitrace/actions/workflows/ci.yml)

[English](README.en.md) · [中文](README.md)

> **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:**

```bash
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

```bash
pip install scitrace
```

Add to your MCP client config:

```json
{
  "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 |

```json
{
  "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):

```bash
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. Official drop-in templates (≤10 lines each):

| Client | Template | Where to put it |
|:---|:---|:---|
| Claude Desktop | [`prompts/claude-desktop.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/claude-desktop.md) | Project Instructions / `CLAUDE.md` |
| Cursor | [`prompts/cursor.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/cursor.md) | `.cursor/rules/scitrace.mdc` |
| Codex CLI | [`prompts/codex-agents.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/codex-agents.md) | `AGENTS.md` in the project root |
| Hermes | [`prompts/hermes.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/hermes.md) | system prompt / skill |

Four conventions are enough:

1. **When to record**: call `build_trace` after each verifiable reasoning subtask — not after every sentence
2. **ID conventions**: `step_id` only needs to be unique within a trace; use a meaningful `trace_id` (e.g. `perovskite-2026`)
3. **Record dead ends explicitly** as `type=backtrack` — the most valuable node when reviewing
4. **Cross-session recovery**: start a new session with `query_trace(trace_id=...)` instead of asking the user to re-explain

---

## 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

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

See [CONTRIBUTING.md](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](CHANGELOG.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
- [Development baseline PRD](docs/PRD.md)

---

## License

MIT
