Getting Started
Install once.
Verify quickly.
Inspect every assist.
TraceBase is a reasoning reuse layer for agents. It installs into the agent surface you already use, keeps project-scoped local memory by default, and adds hosted visibility on top without changing the core workflow.
One command install
`npx tracebase-ai init` creates the local store, writes the adapter surface, and links the project into the hosted workspace when browser auth is available.
Operator-first health checks
`status`, `doctor`, `events`, and `report` all read the same local event substrate and now resolve the real project root from nested directories.
Auditability by default
Retrieval, prompt injection, usage attribution, and outcomes stay in one chain so reuse quality can be measured instead of guessed.
Overview
What gets installed
The install path stays small. TraceBase adds a project-scoped memory store, wires the active agent into that store, and writes a managed instruction block so the agent knows when to retrieve and when to report outcomes.
Local store
`.tracebase/` contains the local SQLite store and stable workspace config for the project.
Agent adapter
Depending on the target: `.claude/settings.json`, `~/.cursor/mcp.json`, or the Codex MCP registry.
Managed instructions
`CLAUDE.md` or `AGENTS.md` gets a managed TraceBase block. User content outside that block is preserved.
Quickstart
Three commands. That's the quickstart.
Install, confirm the surface, run a health check. The browser approval step only appears when hosted linking is available — fully offline installs skip it entirely.
What success looks like
`init` reports the selected target, writes the local config, writes the managed instruction file, and links the project into the hosted workspace if you approve in the browser.
What to do immediately after
Restart the target agent, confirm TraceBase appears in the MCP surface, then run `npx tracebase-ai status` from the project.
Integrations
One install. Three agent surfaces.
`init` auto-detects the agent you are running inside, or — on a cold terminal — configures every agent installed on the machine. You never need `--agent` under normal use.
Claude Code
.mcp.json + CLAUDE.md
adapter
- 1Run the command above in your project directory — `init` auto-detects Claude Code and writes `.mcp.json` so 2.x picks the runtime up.
- 2Older installs that wrote into `.claude/settings.json` are migrated automatically — you don't need to clean anything up by hand.
- 3Restart Claude Code so the MCP server boots.
- 4Run `/tools` and confirm `get_reasoning_patterns` is listed.
Cursor
~/.cursor/mcp.json + AGENTS.md
adapter
- 1Run the command above — if Cursor is installed locally, `init` auto-detects it and writes the adapter.
- 2Restart Cursor so MCP reloads.
- 3Open Cursor Settings → MCP and confirm `tracebase` shows a green indicator.
Codex
codex mcp registry + AGENTS.md
adapter
- 1Run the command above — if the `codex` CLI is on PATH, `init` detects Codex and registers the MCP server.
- 2Start a fresh Codex session in the project.
- 3Run `codex mcp list` and confirm `tracebase` is present.
Operate
Verify the install in 10 seconds.
After install you should not have to guess. The local CLI gives you enough signal to tell a fresh project from a broken one, and enough detail to debug adapter wiring without opening the database by hand.
One-screen install snapshot. Shows the resolved project root, target agent, local store path, install surfaces, and recent event counts.
Deep integrity check. Fails on broken config, malformed JSON, missing MCP registration, and other real install defects.
Read the most recent retrieval, injection, fact injection, agent_used, and outcome events from the local store.
Aggregated reuse metrics from the same event substrate used by the dashboard.
Lifecycle
Remove or reset cleanly.
TraceBase has a proper uninstall path. Use it for local testing or to put a project back into a known-clean state before a reinstall.
Removes `.tracebase/`, removes the managed TraceBase section from `CLAUDE.md` or `AGENTS.md`, and unregisters the MCP entry for the active adapter.
Safe cleanup
The command removes only TraceBase-owned surfaces. User content outside the managed instruction block is preserved.
Reinstall loop
For a full reset: `npx tracebase-ai remove` → `npx tracebase-ai init`.
Scope
This is a project uninstall. It does not revoke your dashboard account or delete unrelated agent configuration.
Control plane
The dashboard reads the same event log.
The hosted dashboard is not a separate truth source. It is the visibility layer on top of the same retrieval and outcome events the local CLI reads — nothing is reinterpreted between layers.
What the dashboard should answer
- How often did retrieval fire?
- What actually entered prompts?
- Which blocks and facts were helpful?
- What token or latency delta did reuse create?
Why the audit trail matters
- Enterprises need to inspect what was injected and why.
- Calibration only works if usage attribution is honest.
- Lifecycle repair only works if disproved reasoning can be demoted safely.
retrieval
Candidate blocks and facts surfaced for the run, including shadow retrieval when enabled.
injection / fact_injection
What actually entered the prompt after gating. Prompt payload and analytics stay one-to-one.
agent_used / fact_agent_used
What the agent actually used, intersected with what was truly injected so attribution stays honest.
outcome
Whether the run resolved and whether it was a control run. This closes the calibration and lifecycle loop.
Capabilities
Five arms, one memory.
Each capability catches a specific failure mode agents hit at runtime. Same vocabulary you'll see on the landing — recall, gist, loop, guard, fold — implemented over a single project-scoped store.
Recall
Reasoning reuse — surfaces past solutions when a similar problem returns. Vector + heuristic match against the project-scoped pattern DB.
Gist
Semantic file memory — recalls what a file means without re-reading the bytes. Survives window compaction across long runs.
Loop
Loop detection — catches doom-loops mid-run on a six-turn rolling window. Suggests a redirect, never overrides agent judgement.
Guard
Tool supervision — spots redundant fetches and repeat searches before they compound on the bill. Tool-call dedup window.
Fold
Context compression — folds older turns into gist summaries so long horizons (100+ turns) stay coherent without thrashing the window.
Architecture
Five stages, one loop.
Public docs do not need every internal detail, but they should make the operating loop legible. TraceBase is useful only if the whole loop closes and poor reasoning gets corrected instead of accumulating.
Capture
Successful runs are distilled into reusable blocks and facts.
Recall
New work retrieves candidates from procedural and semantic memory before the agent burns tokens.
Inject
Only gate-passing candidates reach the prompt. Rendered payload and analytics stay aligned.
Measure
Events track retrieval, injection, usage, outcome, and aggregate helpfulness.
Repair
Verification and lifecycle repair demote blocks that stop earning their keep.
Reference
CLI reference.
The commands that matter for rollout, operations, debugging, and analytics. The public surface is intentionally small and composable — every command emits machine-readable output behind `--json`.
Initialize the local store, auto-detect the active agent (or every locally-installed agent), write the adapter surfaces, and link into the hosted workspace when browser auth is available.
Scripting escape hatch. Restrict the install to a single adapter. Most users do not need this — `init` alone picks the right adapter.
Remove `.tracebase/`, the managed instruction block, and the registered MCP entry for the active adapter. User content outside the managed block is preserved.
Machine-readable install snapshot. Same shape the dashboard uses for the installations page.
Machine-readable health report. Exits non-zero when install integrity is broken — wire this into CI for rollout gates.
Structured aggregated reuse analytics from the local event log. Pair with `--limit` and `--after` for windowed reads.
Look up resolved patterns for a problem shape from the project-scoped pattern DB. Useful for inspecting what the agent would have surfaced before opening Claude Code.
30-day reuse + saved-tokens funnel — the same fold the hosted /dashboard/impact page renders, computed locally from the event log.
Per-run cost-delta breakdown across the last N runs. Honest about what was injected versus actually used so attribution stays clean.
Troubleshooting
When things go wrong.
Most install problems are one of four things: wrong adapter, broken local config, missing CLI surface, or a user checking the wrong project root. Verify the specific failure first — don't edit files blind.
Install targeted the wrong agent
`init` auto-detects the agent you are running inside and falls back to every locally-installed agent. If you need to lock it down, re-run with `npx tracebase-ai init --agent cursor` (or `--agent codex`). Auto-selection never picks Codex unless the `codex` CLI is actually available.
Status works in root but not from a subdirectory
This path is fixed. `status`, `doctor`, `events`, and `report` now walk up to the real project root and do not invent phantom nested stores.
Codex adapter says CLI is unavailable
Install the Codex CLI or use another adapter. TraceBase now surfaces this as an incomplete install instead of silently succeeding.
Need a clean reinstall
Run `npx tracebase-ai remove`, then `npx tracebase-ai init`. This removes the local project store and the managed integration surfaces without touching unrelated user content.