# https://github.com/64envy64/tracebase 项目说明书 生成时间：2026-05-15 07:40:14 UTC ## 目录 - [Getting Started](#getting-started) - [Key Concepts](#key-concepts) - [System Architecture](#architecture-overview) - [Block Store](#block-store) - [Retrieval System](#retrieval-system) - [Recall Mechanism](#recall-mechanism) - [Loop Detection](#loop-detection) - [Context Fold](#context-fold) - [SDK Reference](#sdk-reference) - [Agent Adapters](#agent-adapters) ## Getting Started ### 相关页面 相关主题：[Key Concepts](#key-concepts)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/64envy64/tracebase/blob/main/README.md) - [src/cli/commands/init.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/init.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [src/cli/commands/status.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/status.ts) - [www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) - [www/src/components/dashboard/InstallationsView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/InstallationsView.tsx)
# Getting Started TraceBase is an institutional memory layer for AI agents that stores, retrieves, and injects past debugging experiences into new sessions. The Getting Started guide walks you through installing the CLI, linking your first project, running diagnostics, and verifying that memory injection is working correctly. ## Prerequisites Before you begin, ensure your environment meets the following requirements: | Requirement | Version/Details | Notes | |-------------|-----------------|-------| | Node.js | 18.x or later | Required for the CLI | | npm or yarn | Latest stable | For package installation | | Supported Agents | Claude Code, custom runtimes | Hook configuration varies by agent | | Git | Any recent version | For project integration | 资料来源：[www/src/components/dashboard/OverviewView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) ## Installation The TraceBase CLI is distributed as an npm package and can be initialized in any project directory. ```bash npx tracebase-ai init ``` Running this command in a project directory creates the necessary configuration files and links the project into your TraceBase workspace. 资料来源：[www/src/components/dashboard/OverviewView.tsx:12](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/OverviewView.tsx) ## Project Initialization Flow ```mermaid graph TD A[npx tracebase-ai init] --> B{Check project root} B -->|Valid project| C[Create .tracebase config] B -->|No project| D[Error: run in project dir] C --> E[Create instruction block in CLAUDE.md/AGENTS.md] E --> F[Configure agent hooks] F --> G[Verify with tracebase-ai doctor] G --> H{All checks pass?} H -->|Yes| I[Project linked successfully] H -->|No| J[Review doctor output] J --> K[Fix issues] K --> G ``` ### What `init` Configures The initialization process sets up several components: 1. **Project Configuration** — Creates `.tracebase/config.json` with project metadata 2. **Instruction Block** — Appends a managed section to `CLAUDE.md` or `AGENTS.md` that defines the injection protocol 3. **Agent Hooks** — Configures the appropriate hooks for your agent (e.g., Claude Code hooks via `.claude/settings.json`) 资料来源：[src/cli/commands/init.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/init.ts) 资料来源：[src/cli/commands/doctor.ts:1-30](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Diagnostic Check After initialization, run the diagnostic command to verify your setup: ```bash tracebase-ai doctor ``` The doctor command performs the following checks: ### Instruction File Checks | Check | Condition | Severity | Fix | |-------|-----------|----------|-----| | File existence | `CLAUDE.md` or `AGENTS.md` present | warn | Run `init` | | Managed section | Managed block appended to instruction file | warn | Re-run `init` | | Validation | Managed section content is valid | error | Check file syntax | 资料来源：[src/cli/commands/doctor.ts:20-35](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ### Hook Health Checks Hook health inspection is specific to Claude Code and is surfaced as a separate check from MCP configuration because the two surfaces are independent. MCP can be perfectly configured while `.claude/settings.json` has no hook entries, silently degrading the default UX where users lose silent injection and background capture, falling back to the foreground MCP permission prompt. | Check | Description | Regression Caught | |-------|-------------|-------------------| | Hook configuration | Verifies events are registered in `.claude/settings.json` | MCP + CLAUDE.md OK but stop hook missing | | Event presence | Checks managed events exist for the current agent | Hooks not wired to TraceBase | 资料来源：[src/cli/commands/doctor.ts:45-60](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Project Linking Once initialized, projects appear in the TraceBase dashboard under **Installations**. Each linked project displays: - **Project Name** — The directory name or configured project identifier - **Agent** — Which agent is configured (e.g., Claude Code) - **CLI Version** — Installed TraceBase CLI version if available - **Timestamps** — When the project was linked and last updated ```typescript interface Installation { id: string; projectName: string; agent: string; cliVersion?: string; createdAt: Date; updatedAt: Date; } ``` 资料来源：[www/src/components/dashboard/InstallationsView.tsx:1-40](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/InstallationsView.tsx) ## Verification Steps ### 1. Confirm Installation Appears in Dashboard After running `npx tracebase-ai init`, navigate to your TraceBase workspace dashboard. The linked project should appear in the **Installations** list within a few seconds. ### 2. Run Agent Session with Memory Start a new agent session in the linked project. When the agent encounters a task, TraceBase: 1. Checks the memory knowledge base for relevant past experiences 2. Retrieves matching blocks (situation, mechanism, dead ends, unlock) 3. Injects high-confidence matches into the agent context ### 3. Verify Memory Capture After any session that touched memory, run the dashboard to see the activity log. Successful memory operations appear as **Used** events in the task funnel. 资料来源：[www/src/components/dashboard/ImpactView.tsx:10-50](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/ImpactView.tsx) ## Troubleshooting | Symptom | Likely Cause | Resolution | |---------|--------------|------------| | Doctor shows "instruction file missing" | `CLAUDE.md`/`AGENTS.md` not found | Run `npx tracebase-ai init` | | Doctor shows "managed section missing" | Instruction file exists but no managed block | Re-run `npx tracebase-ai init` | | Agent not receiving injections | Hooks not configured | Check `.claude/settings.json` for hook entries | | Dashboard shows no installations | Project not linked | Run `npx tracebase-ai init` in project directory | 资料来源：[src/cli/commands/doctor.ts:15-25](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Next Steps After completing the Getting Started guide: 1. **Connect repositories** — Link GitHub repos to pull in issues, PRs, and CI failures for the Engineering Brain 2. **Review the whitepaper** — Understand the evaluation methodology and benchmark results 3. **Configure custom integrations** — If using a custom agent runtime, explore the integration options --- ## Key Concepts ### 相关页面 相关主题：[Getting Started](#getting-started), [System Architecture](#architecture-overview)
Relevant Source Files 以下源码文件用于生成本页说明： - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [src/distillation/llm-distiller.ts](https://github.com/64envy64/tracebase/blob/main/src/distillation/llm-distiller.ts) - [www/src/components/landing/HeroInk.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/landing/HeroInk.tsx) - [www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx)
# Key Concepts TraceBase is a memory layer for coding agents that preserves past solutions, file meaning, and doom-loop patterns across runs. It operates as a drop-in MCP (Model Context Protocol) server that enables agents to retain and retrieve institutional knowledge. ## Architecture Overview TraceBase employs a two-stage retrieval architecture with six distinct signals and learned ranking weights. ```mermaid graph TD A[Agent Query] --> B[Stage 1: Fingerprint + BM25] B --> C[Candidate Set] C --> D[Stage 2: Re-ranking] D --> E[Structural Signal] D --> F[Cosine Signal] D --> G[Freshness Signal] E --> H[Thompson Sampling Ranker] F --> H G --> H H --> I[Final Block Injection] ``` **Retrieval Signals:** | Signal | Purpose | |--------|---------| | Fingerprint | O(1) exact match lookup | | BM25 (FTS5) | Full-text search candidate narrowing | | Structural | Code structure relevance | | Cosine | Semantic similarity | | Freshness | Recency weighting | Weights are learned from outcomes via Thompson sampling. 资料来源：[www/src/app/whitepaper/page.tsx:48-58]() ## Core Data Model: Blocks Blocks are the fundamental memory units in TraceBase. Each block encapsulates a learned solution pattern with structured metadata. ### Block Structure ```mermaid graph LR A[Block] --> B[Trigger] A --> C[Body] B --> D[situation] B --> E[invariants] C --> F[mechanism] C --> G[deadEnds] C --> H[unlock] C --> I[verification] C --> J[guardrails] ``` **Trigger (situation):** The context or problem scenario that activates this memory block. **Invariants:** Conditions that must hold true for the block to be relevant. **Body Components:** | Field | Purpose | Citation | |-------|---------|----------| | `mechanism` | Root cause explanation | [src/core/block-serving.ts:31]() | | `deadEnds` | Known failure paths to avoid | [src/core/build-injection-payload.ts:31]() | | `unlock` | The fix or solution approach | [src/distillation/llm-distiller.ts:52]() | | `verification` | How to confirm the fix works | [src/core/block-serving.ts:34]() | ### Prose Rendering When a block is injected into agent context, it renders as compact prose: ``` • . Mechanism: <…>. Fix: . Verify: . ``` Dead ends append an `Avoid:` clause when present. 资料来源：[src/core/build-injection-payload.ts:20-38]() ### Imported Blocks Blocks can be marked as `imported` with a special XML tag wrapper: ```xml … ``` This distinction is used for blocks extracted from external knowledge sources versus local agent experience. 资料来源：[src/core/build-injection-payload.ts:12-15]() ## Multi-Round Methodology TraceBase implements a compound-intelligence effect through iterative knowledge accumulation. ```mermaid graph LR A[Round 0] -->|Empty KB| B[Agent Solves Tasks] B -->|Successful patches| C[Traces Created] C --> D[Round 1] D -->|Warm KB| E[Agent Solves Same Tasks] E --> F[Improved Accuracy] ``` **Round 0:** Baseline execution with empty knowledge base. Successful solutions become traces. **Round 1:** Same tasks executed with populated knowledge base. Both rounds use identical step caps, cost caps, and Docker images—the only variable is KB state. This simulates production compound-intelligence as agents accumulate institutional knowledge. 资料来源：[www/src/app/whitepaper/page.tsx:105-120]() ## Security: Guardrails TraceBase implements multiple security patterns to prevent injection attacks and spoofing. ### Detection Patterns | Guard Name | Pattern | Purpose | |------------|---------|---------| | `system-spoof` | `(?(?!\`)` | Detects inline `` or `` tags attempting privilege escalation | | `delimiter-spoof` | `(```\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\b` | Prevents faked TraceBase delimiters | The system-spoof pattern includes backtick-neighbour skip logic: documented tags wrapped in inline backticks (e.g., "the `` block marker") are treated as documentation, not spoofed markers. 资料来源：[src/core/guard.ts:25-40]() ### Guardrail Metadata Blocks can contain `guardrails` arrays that constrain their applicability. These are validated during distillation: ```typescript if (filtered.length > 0) guardrails = filtered; ``` Guardrails must be non-empty strings. 资料来源：[src/distillation/llm-distiller.ts:18-24]() ## Agent Integration ### MCP Hook Configuration TraceBase integrates with agent hooks (Claude Code, MCP) for seamless operation. The hook inspection system verifies: 1. MCP server configuration 2. `.claude/settings.json` hook entries 3. Managed events for each agent type Missing Stop hooks are a critical regression—MCP can be configured correctly while hooks silently fail. 资料来源：[src/cli/commands/doctor.ts:35-52]() ### CLI Initialization Projects initialize TraceBase with: ```bash npx tracebase-ai init ``` This creates the instruction block and configures agent hooks. The `doctor` command validates installation: ``` ✓ managed section present ✓ hook-events present ``` ### Installation Tracking Installations are tracked with: | Field | Description | |-------|-------------| | `id` | Unique installation identifier | | `projectName` | Project directory name | | `agent` | Agent type (e.g., Claude Code) | | `cliVersion` | CLI version if available | | `createdAt` | Link timestamp | | `updatedAt` | Last activity timestamp | 资料来源：[www/src/components/dashboard/InstallationsView.tsx:28-45]() ## Block Serving: XML Rendering For audit and debugging purposes, blocks can be rendered as structured XML: ```xml Token handling in nested contexts ... Approach A Approach B ... ... ``` The `calibrated` attribute shows the probability score, and `evidence` elements reference source traces. 资料来源：[src/core/block-serving.ts:28-53]() ## Evaluation Framework TraceBase is evaluated on SWE-bench Verified using mini-swe-agent v2 in Docker containers. **Metrics:** | Metric | Description | |--------|-------------| | Patches | Number of successful patches generated | | Accuracy | Tasks solved / total tasks | | Step save | Reduction in agent steps | | Token save | Reduction in token consumption | Benchmark results show +25% accuracy improvement and up to 39% token savings on Claude Sonnet 4.6. 资料来源：[www/src/app/whitepaper/page.tsx:70-95]() ## Distillation Pipeline The LLM distiller extracts blocks from agent sessions with confidence scoring: **Validation Rules:** | Field | Constraint | |-------|------------| | `distillationConfidence` | Finite number in [0,1] | | `situation` | Non-empty trimmed string | | `mechanism` | Non-empty trimmed string | | `unlock` | Non-empty trimmed string | The extractor uses balanced-brace scanning for nested JSON objects rather than regex, accommodating model-generated nested structures. 资料来源：[src/distillation/llm-distiller.ts:42-60]() ## Impact Funnel TraceBase tracks memory usage through a funnel: ```mermaid graph TD A[Eligible Runs] --> B[Recalled Runs] B --> C[Injected Runs] C --> D[Used Runs] D --> E[Task Win] ``` **Funnel Stages:** | Stage | Definition | |-------|------------| | Agent tasks | Tasks where TraceBase checked memory | | Matched memory | Found at least one relevant block | | Shown | Block was added to agent context | | Used | Agent acted on the memory | 资料来源：[www/src/components/dashboard/ImpactView.tsx:30-50]() ## Key Design Principles 1. **Positive constraints over negative framing** — "the bug is X, fix: Y" rather than "do not try A, B, C" 2. **Skip-to-fix when prior knowledge is available** — plan-and-act, not explore-first 3. **Compression for injection** — traces stored as three short fields (situation, deadEnds, unlock) for efficient context addition 4. **Compound intelligence** — patterns that work for one team raise match quality for everyone --- ## System Architecture ### 相关页面 相关主题：[Block Store](#block-store), [Retrieval System](#retrieval-system)
Related Source Files The following source files were used to generate this documentation page: - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/core/file-walker.ts](https://github.com/64envy64/tracebase/blob/main/src/core/file-walker.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts)
# System Architecture TraceBase is a compound-intelligence knowledge base system designed to improve AI agent performance by storing, retrieving, and injecting institutional knowledge into agent contexts. The system compounds over time: patterns that work for one team's agents raise match quality for everyone running the same shapes of work. ## Overview TraceBase operates on a retrieval-augmented principle where successful agent solutions are captured as traces and later re-injected into similar future tasks. This creates a compounding effect where the knowledge base grows more valuable as more agents contribute solutions. The architecture follows a multi-stage pipeline: ```mermaid graph TD A[Agent Session] -->|Completes Task| B[Trace Capture] B -->|Stores| C[Knowledge Base] C -->|Retrieval| D[Two-Stage Ranker] D -->|Fingerprint + BM25| E[Candidate Set] E -->|4 Re-rank Signals| F[Scored Blocks] F -->|Build Payload| G[Injection Block] G -->|Security Guard| H[Validated Payload] H -->|Context Injection| I[Future Agent Session] ``` **Key Components:** | Component | Role | File Reference | |-----------|------|----------------| | Knowledge Store | Persistent trace storage | `src/core/store.ts` | | File Walker | Project indexing | `src/core/file-walker.ts` | | Block Builder | Payload construction | `src/core/build-injection-payload.ts` | | Block Server | Block rendering/ranking | `src/core/block-serving.ts` | | Security Guard | Input validation | `src/core/guard.ts` | ## Retrieval Architecture ### Two-Stage Ranking TraceBase implements a two-stage retrieval ranker for efficiency and accuracy: **Stage 1 - Candidate Narrowing:** - **Fingerprint matching**: O(1) lookup for exact/similar patterns - **BM25 via FTS5**: Full-text search to narrow candidates **Stage 2 - Re-ranking:** Four additional signals re-rank the candidate set: ```mermaid graph LR A[Candidates] --> B[Structural Signal] A --> C[Cosine Similarity] A --> D[Freshness Score] A --> E[Unknown Signal] B --> F[Weighted Rank] C --> F D --> F E --> F F --> G[Final Ranking] ``` | Signal | Purpose | |--------|---------| | Structural | File/code structure relevance | | Cosine | Semantic similarity via embeddings | | Freshness | Recency of the trace | | Fourth Signal | Additional ranking factor | Weights are learned from outcomes via Thompson sampling. 资料来源：[www/src/app/whitepaper/page.tsx]() ## Knowledge Block Structure Traces are stored as compressed three-field blocks optimized for agent steering: ```typescript interface BlockHit { block: { id: string; trigger: { situation: string; // Problem context description }; body: { mechanism: string; // Root cause explanation deadEnds: string[]; // Paths to avoid unlock: string; // Solution approach verification: string; // How to confirm fix }; }; calibratedProb: number; // Match confidence refs: TraceRef[]; // Evidence traces } ``` | Field | Purpose | Example | |-------|---------|---------| | `situation` | Problem context | "React component re-renders on unrelated state change" | | `deadEnds` | Paths to avoid | "Don't wrap in useMemo without memoizing dependencies" | | `unlock` | Solution approach | "Check if parent passes new object reference" | The three-field design prioritizes compression and dead-end steering over verbose documentation. 资料来源：[src/core/block-serving.ts](), [src/core/build-injection-payload.ts]() ## Block Rendering System ### Silent Block Format The block builder generates compact bullet-format traces: ``` • . Mechanism: <…>. Fix: . Verify: . ``` Dead ends are appended when present: ``` • . Mechanism: <…>. Fix: . Verify: . Avoid: ; . ``` Imported traces receive special wrapping: ```xml ... ``` ### XML Audit Format For detailed auditing, blocks render to structured XML: ```xml ... ... ... ... ... ``` The `calibrated` attribute represents the probability that this block matches the current task context. 资料来源：[src/core/block-serving.ts]() ## Security Guard System The guard module provides input validation against injection attacks: ### Guard Patterns ```typescript interface GuardPattern { name: string; re: RegExp; } ``` | Guard Name | Pattern | Purpose | |------------|---------|---------| | `system-spoof` | `/(?(?!`)/i` | Block fake turn markers in backticks | | `delimiter-spoof` | `/(```\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\b\|<\s*(prior_fix\|file_memory\|context_fold)\b)/i` | Prevent riding on injection prefixes | ### Spoof Categories **System Tag Spoofing:** - Inline `…` or `` tags faking higher-privilege turns - Backtick-neighbour skip: documented tags in backticks (e.g., "the `` block marker") are allowed - Raw injected tags still match **Delimiter Spoofing:** - Fake TraceBase delimiters like ` ```prior_fix\n…\n``` ` to inherit trust levels - Patterns include: `system`, `tool_result`, `prior_fix`, `file_memory`, `context_fold` **Secret Exfiltration:** - Targets verbose `environment variable(s)?` form to reduce false positives - Avoids matching benign code prose like "print env var name" The guard intentionally avoids matching shorter patterns like `env` alone, which appear frequently in documentation. 资料来源：[src/core/guard.ts]() ## File Walking System The file walker indexes project repositories for knowledge base population: ```typescript interface WalkOptions { baseRoot?: string; // BFS start point (defaults to root) budget?: WalkBudget; // Time/size constraints maxBytes?: number; // Per-file size cap (default 256 KiB) now?: () => number; // Time override for tests } ``` ### Contract Guarantees - Relative paths are computed against `baseRoot` when specified - BFS starts at `root` but yields files with `relPath = path.relative(baseRoot, abs)` - Caller ensures `root` is inside `baseRoot` - Out-of-base paths surface as `..`-prefixed and fail the repo-rel guard ### Output Types ```typescript interface WalkedFile { relPath: string; // Relative path from base content: string; // File contents sizeBytes: number; // File size } interface SkippedFile { relPath: string; // Local-only path reason: "binary" | "too-large" | "excluded" | "error"; } ``` Files larger than `maxBytes` are skipped with reason `'too-large'`. Binary files are detected and excluded automatically. 资料来源：[src/core/file-walker.ts]() ## Agent Integration TraceBase integrates with AI agents through a multi-step hook system: ### Hook Inspection The CLI `doctor` command validates agent configuration: ```typescript const hookInspection = inspectAgentHookConfig(projectRoot, agent); ``` Checks include: - MCP server configuration - `.claude/settings.json` hook entries - Managed events for the current agent ### Event Mapping Managed events vary by agent type: ```typescript const managedEvents = hookEventsForAgent(agent); // e.g., ['on_tool_call', 'on_result', 'on_context_push'] ``` The system differentiates between MCP surface and Claude Code hook surface, catching regressions where MCP is configured but stop hooks are missing. 资料来源：[src/cli/commands/doctor.ts]() ## Configuration System ### Instruction File Management Projects require a managed instruction block: ```typescript if (!instruction.present) { // Warn: instruction file missing } else if (!instruction.managed) { // Warn: managed section missing } else { // Pass: managed section present } ``` Initialization command: `npx tracebase-ai init` ### Initialization Checks | Check | Level | Fix | |-------|-------|-----| | Instruction file present | warn | Run `init` command | | Managed section present | warn | Re-run `init` | | Hook configuration | pass/warn | Inspect agent hooks | ## Data Flow Summary ```mermaid graph TD subgraph Indexing A1[File Walker] --> A2[Project Files] A2 --> A3[Skipped Files] A3 -->|Binary/Large| A4[Excluded] A2 --> A5[Indexed Files] A5 --> A6[Knowledge Store] end subgraph Retrieval A6 --> R1[Fingerprint Lookup] A6 --> R2[BM25 FTS5] R1 --> R3[Candidate Set] R2 --> R3 R3 --> R4[4 Signal Re-ranker] R4 --> R5[Ranked Blocks] end subgraph Injection R5 --> B1[Block Builder] B1 --> B2[Compact Bullet Format] B2 --> G1[Security Guard] G1 -->|Pass| I1[Context Injection] G1 -->|Fail| G2[Validation Error] end ``` ## Key Design Principles 1. **Compression**: Traces use three-field format to minimize context overhead 2. **Dead-end steering**: Explicit path avoidance prevents repeated exploration 3. **Trust inheritance prevention**: Guard system blocks injection attacks 4. **Compound intelligence**: Library growth improves match quality across all users 5. **Reproducibility**: All benchmark data and seeds are version-controlled 资料来源：[www/src/app/whitepaper/page.tsx]() ## Component Interactions | Interaction | Description | |-------------|-------------| | File Walker → Store | Indexes project files into searchable traces | | Store → Ranker | Provides candidate blocks for retrieval | | Ranker → Block Builder | Delivers scored blocks with calibrated probabilities | | Block Builder → Guard | Validates rendered payloads before injection | | Guard → Agent Context | Injects validated knowledge blocks | --- ## Block Store ### 相关页面 相关主题：[System Architecture](#architecture-overview), [Retrieval System](#retrieval-system)
Related Source Files 以下源码文件用于生成本页说明： - [src/core/block-store.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-store.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/block.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block.ts) - [src/kb/jsonl.ts](https://github.com/64envy64/tracebase/blob/main/src/kb/jsonl.ts) - [src/distillation/llm-distiller.ts](https://github.com/64envy64/tracebase/blob/main/src/distillation/llm-distiller.ts) - [src/server/mcp-v2-helpers.ts](https://github.com/64envy64/tracebase/blob/main/src/server/mcp-v2-helpers.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts)
# Block Store ## Overview The Block Store is the persistent knowledge repository that captures, stores, and retrieves reasoning patterns extracted from agent behavior. It enables agents to learn from past problem-solving experiences and apply that knowledge to similar future tasks. Block Store operates as a **two-tier system**: candidate blocks represent newly extracted patterns awaiting validation, while active blocks represent high-confidence patterns ready for retrieval and injection into agent contexts. 资料来源：[src/server/mcp-v2-helpers.ts:63-75]() ## Data Model ### Block Structure Each block consists of two primary components: a **trigger** and a **body**, along with metadata for calibration and provenance tracking. | Field | Type | Description | |-------|------|-------------| | `id` | `string` | Unique identifier for the block | | `trigger.situation` | `string` | Short trigger statement describing when the pattern applies | | `trigger.invariants` | `string[]` | Conditions that must be true for the block to apply | | `body.mechanism` | `string` | Explanation of why the fix works | | `body.deadEnds` | `string[]` | Failed approaches to avoid | | `body.unlock` | `string` | The actual fix or solution | | `body.verification` | `string` | How to confirm the fix works | | `body.guardrails` | `string[]` | Safety constraints (optional) | | `calibratedProb` | `number` | Confidence score in range [0, 1] | | `provenance` | `object` | Source tracking (extracted or imported) | | `distillationConfidence` | `number` | Model confidence during extraction | ### Block Provenance Blocks track their origin through the `provenance` field: | Provenance Value | Meaning | |-----------------|---------| | `extractedFrom: "extracted"` | Manually stored via MCP tool | | `extractedFrom: "imported"` | Inherited from prior project via migration | | `extractedFrom: "distilled"` | Auto-generated from outcome analysis | 资料来源：[src/distillation/llm-distiller.ts:89-100]() ## Architecture ```mermaid graph TD subgraph Extraction A[Agent Execution] --> B[Outcome Logging] B --> C[LLM Distiller] C --> D[Candidate Block] end subgraph Storage D --> E[SQLite: reasoning_blocks] E --> F{Calibration} F --> G[Active Block] F --> H[Candidate Block] end subgraph Retrieval G --> I[Fingerprint + BM25] I --> J[Re-ranker] J --> K[Top-K Block Hits] end subgraph Injection K --> L[build-injection-payload] L --> M[Compact Bullet Format] M --> N[Agent Context] end ``` ## Storage Layer Block Store uses **SQLite** as its persistence mechanism, storing blocks in the `reasoning_blocks` table. 资料来源：[src/cli/commands/doctor.ts:89-104]() ### Database Schema The store file is located at `.tracebase/memory.db` within the project directory. Blocks are queried using fingerprint matching for O(1) candidate narrowing. ### Store Operations | Operation | Description | |-----------|-------------| | `storeReasoningPattern` | Write new candidate block and promote to active | | `get_reasoning_patterns` | Read from `reasoning_blocks` table (v2 path) | | `get_block_hits` | Retrieve calibrated blocks for injection | > **Important**: The v2 `reasoning_blocks` table is distinct from the legacy `ReasoningTrace` table used by the v1 `store` MCP tool. Blocks stored via the legacy path are not visible to the v2 retrieval system. 资料来源：[src/server/mcp-v2-helpers.ts:48-62]() ## Retrieval Pipeline ### Two-Stage Rank Block retrieval follows a two-stage ranking approach: 1. **Candidate Narrowing** (O(1)): Fingerprint matching identifies potential blocks 2. **Full-text Search**: BM25 via FTS5 provides additional candidate filtering 3. **Re-ranking**: Four signals re-rank the candidates 4. **Thompson Sampling**: Weights learned from outcomes 资料来源：[www/src/app/whitepaper/page.tsx:1]() ### Re-ranking Signals | Signal | Description | |--------|-------------| | Structural | Code structure similarity | | Cosine | Embedding similarity | | Freshness | Recency of extraction | | Outcome | Historical success rate | Weights are learned via Thompson sampling from historical outcomes. 资料来源：[www/src/app/whitepaper/page.tsx:1]() ## Injection Format ### Compact Bullet Format When blocks are injected into agent context, they are rendered as compact bullet points to minimize token usage: ``` • . Mechanism: <…>. Fix: . Verify: . ``` Dead ends are appended when present: ``` • . Mechanism: <…>. Fix: . Verify: . Avoid: a; b; c. ``` ### XML Audit Format For debugging and audit purposes, blocks can be rendered as XML: ```xml Null pointer in config initialization Config object not initialized before use Retry initialization Use default config Add null check and initialize before first access Run config validation test ``` 资料来源：[src/core/block-serving.ts:42-60]() ### Imported Tag Wrapper Blocks imported from other projects are wrapped with a source tag: ```xml • Situation. Mechanism: ... ``` This allows the system to track cross-project knowledge transfer. 资料来源：[src/core/build-injection-payload.ts:6-8]() ## Distillation Process ### LLM Distiller The distillation process extracts reasoning patterns from agent execution logs using an LLM. Input validation ensures: | Field | Constraint | |-------|------------| | `distillationConfidence` | Finite number in [0, 1] | | `situation` | Non-empty string, trimmed | | `mechanism` | Non-empty string, trimmed | | `unlock` | Non-empty string, trimmed | | `verification` | Non-empty string, trimmed | | `deadEnds` | Array of strings, duplicates removed | | `invariants` | Array of strings, duplicates removed | The distiller uses balanced-brace scanning to extract JSON from LLM responses, handling nested objects and arrays robustly. 资料来源：[src/distillation/llm-distiller.ts:70-95]() ### Guardrails Optional `guardrails` field can constrain when a block should apply: ```typescript if (guardrails !== undefined) { // Apply guardrail constraints } ``` ## Security: Delimiter Spoofing Block Store includes guard mechanisms to prevent injection attacks through fake delimiters: | Pattern | Purpose | Regex | |---------|---------|-------| | `delimiter-spoof` | Detect fake TraceBase delimiters | `/(```\\s*(system\|tool_result\|prior_fix\|file_memory\|context_fold)\\b\|<\\s*(prior_fix\|file_memory\|context_fold)\\b)/i` | This prevents attackers from wrapping malicious content in our trusted injection syntax. 资料来源：[src/core/guard.ts:1]() ## CLI Operations ### Doctor Command The `tracebase doctor` command validates store health: | Check | Status | Fix | |-------|--------|-----| | `store-content` (pass) | N active, M candidate blocks | — | | `store-content` (warn) | No blocks in store | Use MCP `store` tool or `tracebase store` | | `store-content` (fail) | Database read failed | Backup, remove `.tracebase/memory.db`, let MCP recreate | The command also validates MCP server connectivity by spawning the registered MCP command with `--selftest`. 资料来源：[src/cli/commands/doctor.ts:89-120]() ## State Diagram ```mermaid stateDiagram-v2 [*] --> Candidate: storeReasoningPattern Candidate --> Active: Promotion Active --> Archived: Deprecated Candidate --> Discarded: Low confidence Active --> Active: Re-calibration ``` ## Configuration Options | Option | Default | Description | |--------|---------|-------------| | `store.file` | `.tracebase/memory.db` | SQLite database path | | `store.activeThreshold` | Calibrated probability threshold | Minimum confidence for active status | | `retrieval.maxHits` | — | Maximum blocks per retrieval | | `retrieval.signals` | [structural, cosine, freshness, outcome] | Re-ranking signal weights | ## Best Practices 1. **Store Meaningful Patterns**: Extract blocks from successful resolutions, not failed attempts 2. **Keep Situations Short**: The trigger should be a concise problem description 3. **Include Dead Ends**: Document what doesn't work to help agents avoid wasted effort 4. **Verify Before Storing**: Ensure the verification step actually confirms the fix 5. **Calibration Matters**: Lower confidence blocks remain candidates until enough positive outcomes raise their score ## Related Components | Component | Role | |-----------|------| | `build-injection-payload.ts` | Renders blocks into compact text for context injection | | `block-serving.ts` | XML and markdown rendering for audit/debugging | | `llm-distiller.ts` | Extracts patterns from execution logs | | `mcp-v2-helpers.ts` | MCP tool implementations for v2 API | | `doctor.ts` | CLI validation and diagnostics | --- ## Retrieval System ### 相关页面 相关主题：[Block Store](#block-store), [Recall Mechanism](#recall-mechanism)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/fingerprint.ts](https://github.com/64envy64/tracebase/blob/main/src/core/fingerprint.ts) - [src/core/similarity.ts](https://github.com/64envy64/tracebase/blob/main/src/core/similarity.ts) - [src/embeddings/openai.ts](https://github.com/64envy64/tracebase/blob/main/src/embeddings/openai.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts)
# Retrieval System ## Overview The Retrieval System is TraceBase's core mechanism for matching incoming agent tasks against a knowledge base of prior problem-solving traces. It serves as the foundation for the compound-intelligence effect—enabling agents to benefit from institutional knowledge accumulated across team workflows. The system's primary purpose is to identify relevant prior solutions when an agent encounters a problem "shape" it has seen before, thereby reducing agent steps, token consumption, and overall task completion cost. 资料来源：[www/src/app/whitepaper/page.tsx]()() ## Architecture The retrieval pipeline implements a **two-stage ranking architecture**: 1. **Candidate Narrowing** (Stage 1): Fingerprint and BM25 rapidly filter the candidate set using O(1) lookups and FTS5 full-text search respectively 2. **Re-ranking** (Stage 2): Four additional signals re-rank the narrowed candidates to surface the most contextually relevant traces ```mermaid graph TD A[Query: Task Description] --> B[Stage 1: Candidate Narrowing] B --> C[Fingerprint
Exact Match] B --> D[BM25
FTS5 Lexical Search] C --> E[Candidate Set] D --> E E --> F[Stage 2: Re-ranking] F --> G[Jaccard
Token Overlap] F --> H[Structural
Feature Matching] F --> I[Cosine
Semantic Similarity] F --> J[Freshness
Temporal Decay] G --> K[Weighted Score] H --> K I --> K J --> K K --> L[Ranked Results] L --> M[Top-K Candidates] ``` 资料来源：[www/src/app/whitepaper/page.tsx]()() ## Retrieval Signals TraceBase employs six distinct retrieval signals, each targeting a specific dimension of similarity. ### Signal Overview | Signal | Type | Purpose | Performance | |--------|------|---------|-------------| | Fingerprint | Exact | Identical problem (O(1) lookup) | Fastest | | BM25 | Lexical | Same keywords, different phrasing | Fast | | Jaccard | Token overlap | Structural keyword matching | Medium | | Structural | Feature | Same error type/language/framework | Medium | | Cosine | Semantic | Embedding similarity | Slower (optional) | | Freshness | Temporal | Recency bias, exponential decay | Fast | 资料来源：[www/src/app/whitepaper/page.tsx]()() ### Fingerprint (Exact Match) The fingerprint signal provides **O(1) lookup** for identical problem detection. This is the fastest signal and serves as the first-line filter for known issues. ```typescript // Pattern from guard.ts - demonstrates exact matching approach { name: "system-spoof", re: /(?(?!`)/i, } ``` The fingerprint implementation uses hash-based deduplication to identify exact matches without scanning the entire knowledge base. ### BM25 (Lexical Search) BM25 performs **FTS5 full-text search** to find candidates sharing keywords but with different phrasing. This handles paraphrased queries that fingerprint would miss. ### Jaccard Similarity The Jaccard signal measures **token overlap** between the query and stored traces. It identifies structural keyword matching beyond simple lexical search. ### Structural Matching Structural signals detect **feature-level similarity**: same error type, same programming language, same framework. This captures semantic patterns that token-based methods might miss. ### Cosine Similarity (Optional) Cosine similarity computes **embedding-based semantic similarity**. This is the slowest signal and is optional, enabled when semantic understanding provides value over lexical methods. 资料来源：[src/embeddings/openai.ts]()() ### Freshness (Temporal Decay) The Freshness signal applies **exponential decay** to recency, implementing a recency bias that prioritizes newer solutions while still surfacing older relevant ones. ## Signal Weighting Signal weights are **learned per project** from outcome events using Thompson sampling, as described in Agrawal & Goyal (2012). ```mermaid graph LR A[Retrieval Event] --> B[Outcome: Helpful?] B --> C[Thompson Sampling] C --> D[Updated Weights] D --> A E[Block Quality] --> F[Wilson Interval Lower Bound] F --> G[Auto-Demotion] ``` Block quality is measured using the **Wilson-interval lower bound** on the helpfulness rate. Blocks that stop earning their keep are automatically demoted. 资料来源：[www/src/app/whitepaper/page.tsx]()() ## Trace Storage Traces are stored as three short fields optimized for compression and agent guidance: | Field | Purpose | |-------|---------| | `situation` | Context description of the problem shape | | `dead_ends` | Common pitfalls and exploration paths to avoid | | `unlock` | Key insight or approach that resolved the issue | This structure is designed to **steer the agent past dead ends** it would otherwise re-explore, referencing the C3oT (arxiv 2412.11664) and TALE (arxiv 2412.18547) approaches. 资料来源：[www/src/app/whitepaper/page.tsx]()() ## Injection Payload Retrieved traces are formatted into injection payloads that the agent can optionally use. The payload construction emphasizes: - **Positive constraints** over negative framing ("the bug is X, fix: Y", not "do not try A, B, C") - **Skip-to-fix** when prior knowledge is available (plan-and-act, not explore-first) The injection system includes a guard layer that prevents spoofed delimiters and malicious content injection: ```typescript // From guard.ts - delimiter spoof prevention { name: "delimiter-spoof", re: /(```\s*(system|tool_result|prior_fix|file_memory|context_fold)\b|<\s*(prior_fix|file_memory|context_fold)\b)/i, } ``` 资料来源：[src/core/guard.ts:line-range]()() ## Data Storage The knowledge base uses **local SQLite with WAL mode** for storage: ```mermaid graph TD A[New Trace] --> B[SQLite WAL] B --> C[Local Index] C --> D[Retrieval Query] D --> C E[Cloud Sync] --> F[Opt-in] F --> B ``` Cloud sync is **opt-in**, allowing teams to control data residency and privacy settings. 资料来源：[www/src/app/whitepaper/page.tsx]()() ## Performance Characteristics | Signal | Time Complexity | Use Case | |--------|------------------|----------| | Fingerprint | O(1) | Exact duplicate detection | | BM25 | O(log n) | FTS5 indexed search | | Jaccard | O(n) | Token overlap scoring | | Structural | O(n) | Feature vector comparison | | Cosine | O(n·d) | Embedding dot products | | Freshness | O(1) | Time-based scoring | ## Configuration The retrieval system supports per-project configuration: - **Signal weights**: Learned via Thompson sampling, not manually configured - **Cosine enablement**: Optional, enables semantic matching when beneficial - **Freshness decay rate**: Configurable temporal weighting - **High-confidence threshold**: Determines when to auto-inject vs. surface for agent decision ## Security Considerations The guard system implements multiple layers of protection: 1. **Backtick-neighbour skip**: Documentation wrapped in inline backticks is not treated as spoofed markers 2. **Delimiter spoof prevention**: Blocks attempts to ride on injection prefixes 3. **Bounded gap detection**: Environment variable exfiltration patterns use verbose forms to reduce false positives 资料来源：[src/core/guard.ts]()() ## Related Components | Component | Relationship | |-----------|--------------| | Fingerprint Module | Exact match detection | | Similarity Module | Jaccard and structural scoring | | Embeddings Module | Cosine similarity computation | | Injection Builder | Payload construction for agents | | Guard Module | Security validation layer | ## Benchmark Results The retrieval system has been validated on: - **SWE-bench Verified**: +5-25% accuracy gains depending on model - **TypeScript fixtures**: 10 verified tests, 100% accuracy maintained across models - **High-confidence match rate**: 55% observed in benchmarks 资料来源：[www/src/app/whitepaper/page.tsx]()() --- ## Recall Mechanism ### 相关页面 相关主题：[Context Fold](#context-fold), [Retrieval System](#retrieval-system)
相关源码文件 以下源码文件用于生成本页说明： - [src/runtime/recall.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/recall.ts) - [src/types.ts](https://github.com/64envy64/tracebase/blob/main/src/types.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/middleware/anthropic.ts](https://github.com/64envy64/tracebase/blob/main/src/middleware/anthropic.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/analytics/usage-metrics.ts](https://github.com/64envy64/tracebase/blob/main/src/analytics/usage-metrics.ts)
# Recall Mechanism The Recall Mechanism is TraceBase's memory retrieval system that enables AI agents to access previously captured problem-solving knowledge during new task execution. It serves as the core pillar of TraceBase's "Learn & Apply" functionality, bridging the gap between isolated problem solutions and ongoing development work. ## Overview The recall system operates through a two-stage retrieval pipeline. First, fingerprint and BM25 searches narrow the candidate set in O(1) and FTS5 lookups respectively. Then, four additional re-ranking signals refine the results before calibrated probabilities are assigned to each candidate. 资料来源：[www/src/app/whitepaper/page.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/app/whitepaper/page.tsx) The mechanism integrates with the agent runtime through middleware wrappers that intercept LLM API calls. When an agent prompt is submitted, the system retrieves relevant reasoning blocks and facts, then injects them into the context window before the model processes the request. ## Recall Entry Points The recall system exposes multiple entry points depending on the type of memory being retrieved: | Entry Point | Scope | Purpose | |-------------|-------|---------| | `recallBlocks()` | Project-wide | Retrieve reasoning blocks across all sessions | | `recallFacts()` | Project/Session | Retrieve factual knowledge with scope filtering | | `recallFiles()` | Project-wide | File-level memory recall (rc.3+) | | `recallChunks()` | Same-session | Context compression recall (rc.6+) | 资料来源：[src/types.ts:types-interface](https://github.com/64envy64/tracebase/blob/main/src/types.ts) ### Chunk-Based Context Compression (rc.6) The `recallChunks` method enables same-session context compression for long-running tasks: ```typescript interface RecallChunksInput { sessionId: string; /** Top-K cap (default 3). Recall is scoped to the same session only. */ k?: number; } interface RecallChunksResult { /** Oldest-first within the K-window. May be empty. */ hits: Array<{ chunkStartTurn: number; chunkEndTurn: number; summary: string; tokensBefore: number; tokensAfter: number; }>; } ``` The folding mechanism compresses `{role, content}[]` turn lists into rolling chunks (8 turns or ≥4k tokens, whichever first). A watermark stored in `session_chunks.MAX(chunk_end_turn)` ensures idempotent behavior. 资料来源：[src/types.ts:RecallChunksInput-RecallChunksResult](https://github.com/64envy64/tracebase/blob/main/src/types.ts) ## Configuration Options The `RecallForPromptOptions` interface defines all configurable parameters for recall operations: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `prompt` | `string` | — | User prompt, already extracted and leakage-bounded by caller | | `basePath` | `string` | — | Project root the call is rooted at | | `sessionId` | `string \| null` | — | Stable Claude Code session ID for fact narrowing | | `tokenBudget` | `number` | `1200` | Soft token budget for `additionalContext`, capped at 2200 | | `toolWindowSize` | `number` | `6` | Number of recent observations for loop detection | | `enableToolDetection` | `boolean` | `true` | Skip loop detector entirely if false | | `fileHitsK` | `number` | `FILE_HITS_DEFAULT_K` | Top-K override for file memory recall (rc.3), max 10 | 资料来源：[src/runtime/recall.ts:RecallForPromptOptions](https://github.com/64envy64/tracebase/blob/main/src/runtime/recall.ts) ### Token Budget Management The token budget controls how much memory content is injected into the context: - **Default soft budget**: 1200 tokens - **Hard cap**: 2200 tokens (enforced by `buildInjectionPayload`) - **Adjustment**: Values above the cap are silently reduced The `clampToBudget` function trims sections to fit within the allocated budget, returning both the clipped sections and a `truncated` flag. 资料来源：[src/lib/control-plane/issue-brief.ts](https://github.com/64envy64/tracebase/blob/main/src/lib/control-plane/issue-brief.ts) ## Middleware Integration ### Anthropic Client Wrapping The recall system integrates with the Anthropic API through a Proxy-based wrapper in `src/middleware/anthropic.ts`: ```typescript export function wrapAnthropic( client: T, layer: ReasoningLayer, recallConfig?: RecallInjectConfig, ): T ``` The wrapper intercepts two methods: | Method | Purpose | |--------|---------| | `messages.create` | Main API call interception | | `messages.stream` | Streaming API interception | 资料来源：[src/middleware/anthropic.ts:wrapAnthropic](https://github.com/64envy64/tracebase/blob/main/src/middleware/anthropic.ts) The wrapping uses a Proxy with an `apply` handler that: 1. Checks if the client is already wrapped (symbol-based guard) 2. Resolves the runtime configuration 3. Applies the recall injection handler to intercepted calls ### Injection Flow ```mermaid graph TD A[Agent Prompt] --> B[Middleware Intercepts] B --> C{recallConfig.enabled?} C -->|false| D[Pass Through] C -->|true| E[Resolve Runtime] E --> F[Retrieve Memories] F --> G[Build Injection Payload] G --> H[clampToBudget] H --> I[Inject into Context] I --> J[LLM Processing] ``` ## Block Retrieval and Rendering ### Block Hit Structure When a reasoning block is matched, it is rendered as a structured block hit: ```typescript interface BlockHit { block: ReasoningBlock; calibratedProb: number; refs: Array<{ traceId: string; role: string; }>; } ``` 资料来源：[src/core/block-serving.ts:renderBlockHitXml](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) ### Compact Rendering Format Block hits are rendered in a compact bullet format: ``` • . Mechanism: . Fix: . Verify: . ``` If dead ends exist, an additional line is appended: ``` Avoid: a; b; c ``` The rendering deliberately avoids mentioning block IDs or calibrated probabilities to maintain clean context that appears as natural guidance rather than tooling output. 资料来源：[src/core/build-injection-payload.ts:renderBlockSilent](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) ### XML Audit Format For audit purposes, blocks can be rendered as XML: ```xml ... ... ... ... ... ``` ## Loop Detection The recall mechanism includes a loop detector that monitors for repetitive tool usage patterns: | Signal Kind | Description | |-------------|-------------| | `straight` | Same tool called repeatedly | | `pingpong` | Alternating between two tools | | `duplicate` | Duplicate tool call detected | 资料来源：[src/sdk/runtime.ts:loop-signals](https://github.com/64envy64/tracebase/blob/main/src/sdk/runtime.ts) Loop detection uses the `toolWindowSize` parameter (default 6) to consider recent observations. When a loop is detected, the system emits a signal with: - `kind: "loop"` or `kind: "tool"` - `label`: Human-readable description (e.g., "▣ TB LOOP straight × 3 (ToolName)") - `count`: Number of repetitions - `toolName`: The tool involved (when applicable) ## Guardrails and Security The recall system includes guardrails to prevent prompt injection attacks: | Guard Rule | Pattern | Purpose | |------------|---------|---------| | `system-spoof` | `(?(?!\`)` | Detect faked turn markers | | `delimiter-spoof` | `(```\s*(system\|tool_result\|prior_fix\|...` | Detect faked TraceBase delimiters | | `env-exfil` | `environment variable` form | Detect environment variable exfiltration | The `system-spoof` rule includes backtick-neighbor skip logic: a documented tag wrapped in inline backticks (e.g., "the `` block marker") is documentation, not a spoofed turn marker. 资料来源：[src/core/guard.ts:system-spoof-delimiter-spoof](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) ## Analytics and Metrics ### Cohort Analysis The recall system tracks usage through two cohorts: | Cohort | Definition | |--------|------------| | **Assisted** | Retrieval event with `shadow === false` AND at least one injection event | | **Holdout** | Retrieval event with `shadow === true` AND `controlReason === "holdout"` | ```typescript interface UsageCausal { assisted: UsageCohort; holdout: UsageCohort; resolvedLift: number | null; tokensLift: UsageEstimate; } ``` The `resolvedLift` is calculated as `assisted.resolvedRate − holdout.resolvedRate` and is null when either arm has fewer than `minCohortSize` outcomes. 资料来源：[src/analytics/usage-metrics.ts:UsageCausal](https://github.com/64envy64/tracebase/blob/main/src/analytics/usage-metrics.ts) ### Token Savings Calculation Token savings are computed as: ``` tokensLift = (mean(holdout.tokens) − mean(assisted.tokens)) × assisted.n ``` This represents the total tokens saved across the measurement window, attributable to the assist feature. ## Session Scoping The recall system implements different scoping rules for different memory types: | Memory Type | Scoping Rule | |-------------|--------------| | Facts (project.session) | Narrowed to `project.session.` | | Facts (project) | Project-wide | | Chunks | **Same-session only** — cross-session recall is structurally impossible due to SQL `session_id` filter | | Files | Project-wide | | Reasoning Blocks | Project-wide | 资料来源：[src/runtime/recall.ts:sessionId-docs](https://github.com/64envy64/tracebase/blob/main/src/runtime/recall.ts) ## Calibration The calibrator assigns probability scores to block hits based on historical accuracy data. The calibration is used to: 1. Rank multiple matching blocks 2. Determine whether to include borderline matches 3. Provide confidence signals for the injection decision Calibrated probabilities appear in audit-mode XML output but are deliberately excluded from silent rendering to maintain clean agent-facing context. ## Summary The Recall Mechanism is a sophisticated retrieval system that: 1. **Retrieves** relevant memory through multi-stage ranking (fingerprint → BM25 → re-ranking) 2. **Configures** retrieval via token budgets, session scoping, and K limits 3. **Injects** matched memory into agent context through middleware interception 4. **Detects** loops using tool observation windows 5. **Secures** the pipeline against prompt injection attacks 6. **Measures** impact through cohort-based analytics 7. **Compresses** long contexts through same-session chunk folding --- ## Loop Detection ### 相关页面 相关主题：[Recall Mechanism](#recall-mechanism)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/sdk/runtime.ts](https://github.com/64envy64/tracebase/blob/main/src/sdk/runtime.ts) - [src/runtime/observe-tools.ts](https://github.com/64envy64/tracebase/blob/main/src/runtime/observe-tools.ts)
# Loop Detection ## Overview Loop Detection is a core runtime mechanism in TraceBase that identifies and signals when a coding agent enters repetitive behavior patterns during tool execution. It serves as a feedback system that allows the system to recognize when an agent is stuck in unproductive cycles, enabling corrective actions such as injecting prior solutions or presenting user-facing notifications. The loop detection system operates by analyzing tool call sequences and categorizing repetitive behavior into distinct pattern types. This information flows through the SDK runtime where it is surfaced as structured signals that can trigger downstream handling. ## Loop Signal Types The system recognizes three primary loop pattern kinds, each representing a different form of repetition: | Kind | Description | Signal Properties | |------|-------------|-------------------| | `straight` | Repeated calls to the same tool | `count`, `toolName` | | `pingpong` | Alternating between two tools | `count`, `toolName` | | `duplicate` | Exact duplicate tool calls | `toolName` | 资料来源：[src/sdk/runtime.ts:1-50]() ### Straight Loops A `straight` loop occurs when an agent repeatedly calls the same tool multiple times in sequence. This pattern is detected when consecutive tool invocations target identical tool names. ```typescript if (signal.kind === "straight" && enableLoop) { return { kind: "loop", label: signal.toolName ? `▣ TB LOOP straight × ${signal.count} (${signal.toolName})` : `▣ TB LOOP straight × ${signal.count}`, count: signal.count, ...(signal.toolName ? { toolName: signal.toolName } : {}), }; } ``` 资料来源：[src/sdk/runtime.ts:1-30]() ### Ping-Pong Loops A `pingpong` pattern emerges when an agent alternates between two different tools back and forth. This indicates the agent is caught in a retry cycle between two approaches. ```typescript if (signal.kind === "pingpong" && enableLoop) { return { kind: "loop", label: signal.toolName ? `▣ TB LOOP ping-pong (${signal.toolName})` : "▣ TB LOOP ping-pong", count: signal.count, ...(signal.toolName ? { toolName: signal.toolName } : {}), }; } ``` 资料来源：[src/sdk/runtime.ts:1-30]() ### Duplicate Detection Duplicate tool calls represent the simplest form of repetition where identical calls are made consecutively. This pattern triggers the `duplicate` kind. ```typescript if (signal.kind === "duplicate" && enableTool) { return { kind: "tool", label: signal.toolName ? `▣ TB LOOP duplicate (${signal.toolName})` : "▣ TB LOOP duplicate", count: signal.count, ...(signal.toolName ? { toolName: signal.toolName } : {}), }; } ``` 资料来源：[src/sdk/runtime.ts:1-30]() ## Tool Input Observation The loop detection system relies on extracting file paths from tool inputs to correlate repeated operations on the same resources. The observation layer supports multiple naming conventions across different agent frameworks. | Supported Key | Framework | |--------------|-----------| | `file_path` | Claude Code | | `path` | LangChain / SDK conventions | | `filename` | Alternative convention | | `filePath` | camelCase variant | ```typescript for (const key of ["file_path", "path", "filename", "filePath"] as const) { const v = obj[key]; if (typeof v === "string" && v.trim().length > 0) return v; } ``` 资料来源：[src/runtime/observe-tools.ts:1-30]() ## Loop Signal Structure Each loop signal includes contextual metadata that enables downstream handlers to make informed decisions: | Property | Type | Description | |----------|------|-------------| | `kind` | `"loop"` | Signal classification | | `label` | `string` | User-visible badge text (max 100 chars) | | `count` | `number` | Number of repetitions detected | | `toolName` | `string` (optional) | Name of the looping tool | | `queryId` | `string` (optional) | Associated query identifier | | `ts` | `number` | Timestamp of detection | | `redirectLabel` | `string` (optional) | Override label for special handling | 资料来源：[src/sdk/runtime.ts:1-30]() ## Integration with Block Serving Loop signals are incorporated into the block serving pipeline where they can trigger injection of previously successful solutions from the knowledge base. The XML rendering format includes calibrated probability scores for hypothesis blocks. ```xml ${escapeXml(hit.block.trigger.situation)} ${escapeXml(hit.block.body.mechanism)} ${escapeXml(hit.block.body.unlock)} ${escapeXml(hit.block.body.verification)} ``` 资料来源：[src/core/block-serving.ts:1-30]() ## User-Facing Loop Indicators When loop detection is enabled, the SDK renders loop badges in the agent interface to provide visual feedback to users. These badges are constructed dynamically based on the detected pattern type. The label generation follows a consistent format: - **Straight loops**: `▣ TB LOOP straight × {count} ({toolName})` - **Ping-pong loops**: `▣ TB LOOP ping-pong ({toolName})` - **Duplicate calls**: `▣ TB LOOP duplicate ({toolName})` 资料来源：[src/sdk/runtime.ts:1-30]() ## Architecture Summary ```mermaid graph TD A[Tool Call] --> B[observe-tools.ts] B --> C[Extract file_path] C --> D[Loop Pattern Analysis] D --> E{Loop Detected?} E -->|No| F[Normal Flow] E -->|Yes| G[Classify Pattern] G --> H{straight | pingpong | duplicate} H --> I[SDK Runtime Signal] I --> J[Enable Loop Check] J -->|Enabled| K[Generate Loop Badge] J -->|Disabled| L[Suppress Signal] K --> M[Block Serving] L --> N[Continue Execution] M --> O[Inject Prior Solutions] ``` ## Configuration Loop detection behavior is controlled through runtime flags: | Flag | Purpose | |------|---------| | `enableLoop` | Enable loop detection and badge rendering | | `enableTool` | Enable tool-level loop classification | | `redirectLabel` | Override default loop label text | 资料来源：[src/sdk/runtime.ts:1-30]() ## Relationship to Dead-End Detection The loop detection system complements the dead-end detection mechanism in the distillation pipeline. While loop detection identifies repetitive tool sequences, dead-end detection analyzes analysis steps to surface abandoned hypotheses. ```typescript // Dead-end detection logic for (let i = 0; i < analyses.length - 1; i++) { const cur = analyses[i]; const next = analyses[i + 1]; if (!hasNegativeSignal(next.description)) continue; const summary = summarizeDeadEnd(cur.description); if (summary && !seen.has(key)) { seen.add(key); deadEnds.push(summary); } } ``` 资料来源：[src/distillation/heuristics.ts:1-30]() ## Summary Loop Detection in TraceBase provides a structured mechanism for identifying repetitive agent behavior through three distinct pattern classifications: straight, pingpong, and duplicate. The system integrates with tool observation to extract file context, generates user-visible indicators via the SDK runtime, and connects to the block serving infrastructure for solution injection. This enables agents to recognize when they are stuck and either self-correct or receive assistance from the knowledge base. --- ## Context Fold ### 相关页面 相关主题：[Recall Mechanism](#recall-mechanism), [Loop Detection](#loop-detection)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [www/src/components/landing/_demo-fixtures/capability-mockups.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/landing/_demo-fixtures/capability-mockups.tsx)
# Context Fold ## Overview Context Fold is a structured memory injection mechanism in TraceBase that allows AI agents to preserve hierarchical, expanded file context within agent prompts. Rather than flattening file context into a simple bullet list, Context Fold maintains structural relationships and metadata about files that an agent has previously explored or analyzed during a session. The feature is referenced throughout the codebase as both a UI presentation concept and a structured injection format. It enables agents to "remember" file exploration context across turns, allowing them to efficiently return to previously analyzed files without redundant exploration. 资料来源：[src/core/guard.ts:17-22]() ## Purpose and Scope Context Fold serves two primary functions within the TraceBase system: 1. **Structured Memory Preservation** - It wraps file context in a structured format that maintains hierarchy (file → sections → lines) rather than converting everything to prose 2. **Injection Security** - The `` delimiter is explicitly protected by the guard system to prevent spoofed injections The feature is particularly relevant when an agent has performed multi-file exploration (referred to in the whitepaper as "explore codebase" phases) and needs to preserve that context for future turns or similar tasks. 资料来源：[www/src/components/landing/_demo-fixtures/capability-mockups.tsx:60-80]() ## Architecture ```graph TD A[Agent Exploration] --> B[File Indexer] B --> C[File Summarizer] C --> D[Context Fold Generation] D --> E[Build Injection Payload] E --> F[Guard Validation] F --> G[Agent Context] H[Guard: context_fold] --> F ``` ### Component Flow | Component | Role | File | |-----------|------|------| | File Indexer | Indexes files during agent exploration | `src/core/file-indexer.ts` | | File Summarizer | Generates summaries of indexed files | `src/core/file-summarizer.ts` | | Context Fold Generator | Creates structured fold format | `src/core/context-fold.ts` | | Build Injection Payload | Assembles final injection with fold | `src/core/build-injection-payload.ts` | | Guard | Validates injection against spoofing | `src/core/guard.ts` | ## Injection Format Context Fold is injected into agent prompts using a dedicated XML-like delimiter format: ``` Utility functions for string manipulation
...
``` This format is distinct from other injection types: | Injection Type | Delimiter | Purpose | |---------------|-----------|---------| | Prior Fix | `` | Resolved bug reasoning traces | | File Memory | `` | Simple file references | | Context Fold | `` | Structured hierarchical file context | The distinction between `file_memory` and `context_fold` is intentional: `file_memory` is a flat reference, while `context_fold` preserves structural depth. 资料来源：[src/core/guard.ts:17-22]() ## Security: Guard Protection The Context Fold delimiter is protected by the TraceBase guard system against injection attacks. The guard pattern `delimiter-spoof` specifically validates that legitimate `context_fold` tags are not being faked: ```javascript { name: "delimiter-spoof", re: /(```\s*(system|tool_result|prior_fix|file_memory|context_fold)\b|<\s*(prior_fix|file_memory|context_fold)\b)/i, } ``` This pattern matches: - Backtick-wrapped faked delimiters: ````prior_fix\n…\n```` - Angle-bracket faked delimiters: `` The guard ensures that only legitimate TraceBase-generated folds are accepted, preventing malicious actors from attempting to inject content by mimicking the delimiter format. 资料来源：[src/core/guard.ts:14-22]() ## UI Presentation In the TraceBase web dashboard and landing page mockups, Context Fold is visualized as part of the "live window" display, showing the agent's current exploration state: ```tsx active} highlight /> ``` The `FoldMockup` component displays how Context Fold appears in the dashboard, showing: - Exploration phases (e.g., "explore codebase") - Turn ranges (e.g., "01–08", "17–22") - Token reduction metrics (e.g., "4.2k → 340") This visualization helps users understand how the agent's exploration context is being compressed and preserved across sessions. 资料来源：[www/src/components/landing/_demo-fixtures/capability-mockups.tsx:60-80]() ## Integration with Block Serving When serving memory blocks to agents, the Context Fold data can be rendered in XML format for structured display. The `renderBlockHitXml` function handles the rendering of block hits, which may include Context Fold data: ```javascript function renderBlockHitXml(hit: BlockHit, audit: boolean): string { const parts: string[] = []; parts.push(` `); parts.push(` ${escapeXml(hit.block.trigger.situation)}`); // ... additional fields including potential context fold data } ``` This XML format provides a machine-readable structure that agents can parse while maintaining semantic clarity for human review during debugging. 资料来源：[src/core/block-serving.ts:55-75]() ## Use Cases Context Fold enables several key workflows: 1. **Multi-file Exploration Memory** - When an agent explores a codebase to understand a bug, Context Fold preserves which files were examined and the insights gained from each 2. **Efficient Context Reuse** - Agents can quickly reference previously explored files without re-reading entire file contents 3. **Hierarchical Compression** - The fold format maintains structure (file → section → content) rather than flattening to prose, preserving searchability 4. **Cross-Session Learning** - When used with the distillation system, Context Fold data from successful agent runs can be stored and replayed for similar future tasks ## Configuration Context Fold behavior is typically configured through the injection payload builder. The `build-injection-payload.ts` module determines when and how folds are included in agent prompts based on: - Relevance scoring from the retrieval system - Calibration probabilities from the block serving layer - Provenance tracking (whether content is "imported" or "extracted") The `wrapIfImported` function applies special formatting for externally imported context folds to distinguish them from internally generated content: ```javascript function wrapIfImported(line: string, imported: boolean): string { return imported ? `${IMPORTED_TAG_OPEN}${line}${IMPORTED_TAG_CLOSE}` : line; } ``` 资料来源：[src/core/build-injection-payload.ts:1-15]() ## Related Components | Component | Relationship | |-----------|-------------| | **Block Serving** | Serves Context Fold data to the injection system | | **Guard System** | Validates Context Fold delimiters against spoofing | | **Heuristics** | Used during distillation to identify dead ends that may become folds | | **File Indexer** | Provides the initial file context that becomes a fold | | **File Summarizer** | Generates summaries that populate fold content | --- ## SDK Reference ### 相关页面 相关主题：[Agent Adapters](#agent-adapters)
Relevant Source Files 以下源码文件用于生成本页说明： - [src/core/block-serving.ts](https://github.com/64envy64/tracebase/blob/main/src/core/block-serving.ts) - [src/core/build-injection-payload.ts](https://github.com/64envy64/tracebase/blob/main/src/core/build-injection-payload.ts) - [src/core/guard.ts](https://github.com/64envy64/tracebase/blob/main/src/core/guard.ts) - [www/src/components/dashboard/InstallationsView.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/dashboard/InstallationsView.tsx) - [www/src/components/landing/HeroInk.tsx](https://github.com/64envy64/tracebase/blob/main/www/src/components/landing/HeroInk.tsx)
# SDK Reference ## Overview TraceBase provides a Software Development Kit (SDK) for integrating its memory layer into coding agent workflows. The SDK enables agents to retain and retrieve institutional knowledge across sessions, including past solutions, file meanings, and patterns that prevent doom-loops. 资料来源：[www/src/components/landing/HeroInk.tsx:1-10]() ## Architecture Overview The SDK operates as a middleware layer that intercepts agent interactions, manages memory retrieval, and injects relevant context into the agent's runtime. The architecture follows a two-stage retrieval pipeline: ```mermaid graph TD A[Agent Session] --> B[Middleware Layer] B --> C[Fingerprint Lookup] B --> D[BM25 FTS5 Lookup] C --> E[Candidate Set] D --> E E --> F[4-Signal Re-ranker] F --> G[Top-K Hits] G --> H[Injection Payload Builder] H --> I[Agent Context] I --> J[Agent Action] ``` 资料来源：[www/src/app/whitepaper/page.tsx:1-50]() ## Core Components ### Middleware Layer The middleware serves as the primary integration point with agent runtimes. It handles: | Component | Purpose | |-----------|---------| | Request Interception | Captures agent prompts and tool outputs | | Memory Retrieval | Queries the knowledge base using multi-signal ranker | | Payload Injection | Formats and inserts relevant memory into context | | Guardrails | Validates injection content for security | 资料来源：[src/core/guard.ts:1-30]() ### Block Serving The block-serving module renders retrieved memory blocks into formatted output suitable for agent consumption: ```typescript // Compact bullet format rendering • . Mechanism: <…>. Fix: . Verify: . ``` | Format | Use Case | |--------|----------| | XML | Structured audit output with evidence traces | | Markdown | Human-readable bullet format | | Silent | Compact single-line format for context windows | 资料来源：[src/core/block-serving.ts:1-45]() ### Injection Payload Builder Builds the memory context that gets injected into agent sessions: ```typescript const IMPORTED_TAG_OPEN = ``; const IMPORTED_TAG_CLOSE = ``; ``` The builder creates compact, natural-language formatted blocks that: - Capitalize the situation description - Trim sentences to essential information - Wrap imported fixes with provenance tags - Include dead-end warnings when applicable 资料来源：[src/core/build-injection-payload.ts:1-35]() ## Integration Patterns ### Supported Integrations TraceBase supports integration through: | Integration Type | Description | |------------------|-------------| | MCP (Model Context Protocol) | Drop-in MCP interface for seamless agent integration | | CLI | `npx tracebase-ai init` for project linking | | Custom Runtimes | Programmatic API for custom agent loops | 资料来源：[www/src/components/landing/HeroInk.tsx:1-10]() ### Installation Tracking The SDK tracks installations across projects: | Field | Description | |-------|-------------| | `projectName` | Name of the linked project | | `agent` | Agent identifier | | `cliVersion` | CLI version if installed | | `createdAt` | Installation timestamp | | `updatedAt` | Last activity timestamp | 资料来源：[www/src/components/dashboard/InstallationsView.tsx:1-40]() ## Retrieval Pipeline The SDK uses a two-stage ranker for memory retrieval: ```mermaid graph LR A[Fingerprint] --> C[Candidates] B[BM25 FTS5] --> C C --> D[Signal 1] C --> E[Signal 2] C --> F[Signal 3] C --> G[Signal 4] D --> H[Re-ranked Results] E --> H F --> H G --> H ``` ### Stage 1: Candidate Narrowing - **Fingerprint Lookup**: O(1) operation for quick candidate filtering - **BM25 FTS5**: Full-text search for semantic matching ### Stage 2: Re-ranking Signals Four additional signals re-rank candidates: 1. **Semantic relevance** 2. **Temporal recency** 3. **Usage frequency** 4. **Project context match** 资料来源：[www/src/app/whitepaper/page.tsx:1-50]() ## Security Model ### Guardrails The SDK implements security checks to prevent injection attacks: | Guard Name | Pattern | Purpose | |------------|---------|---------| | `system-spoof` | `<\s*\/?\s*(system\|user\|assistant)\s*>` | Prevents privilege escalation via spoofed turn markers | | `delimiter-spoof` | `` ```\s*(system\|tool_result\|prior_fix\|...) `` | Blocks injection riding on trusted delimiters | | `env-exfil` | `environment variable` verbose form | Prevents secret exfiltration | The guardrail uses negative lookbehind to avoid false positives from inline backticks: ```typescript /(?(?!`)/i ``` 资料来源：[src/core/guard.ts:1-45]() ### Imported Fix Tagging Imported fixes are wrapped with provenance tags: ```xml ``` This allows agents to understand the origin of solutions and apply appropriate confidence levels. 资料来源：[src/core/build-injection-payload.ts:1-15]() ## Block Data Model ### BlockHit Structure | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique block identifier | | `calibratedProb` | number | Probability score (0-1) | | `situation` | string | Trigger condition description | | `mechanism` | string | Root cause explanation | | `unlock` | string | Fix or workaround | | `verification` | string | How to confirm fix | | `deadEnds` | string[] | Approaches to avoid | | `refs` | Ref[] | Evidence traces | ### FactHit Structure | Field | Type | Description | |-------|------|-------------| | `id` | string | Fact identifier | | `factType` | string | Classification of fact | | `scope` | string | Applicability scope | | `confidence` | number | Confidence score | 资料来源：[src/core/block-serving.ts:1-60]() ## Output Formats ### XML Format (Audit Mode) ```xml Memory allocation fails under load Fragmented heap from rapid allocation/deallocation Enable memory pool with 64KB chunks Run stress test with 10K concurrent requests ``` ### Markdown Format (Agent Context) ``` • Memory allocation fails under load. Mechanism: Fragmented heap from rapid allocation/deallocation. Fix: Enable memory pool with 64KB chunks. Verify: Run stress test with 10K concurrent requests. Avoid: Increasing heap size without addressing fragmentation. ``` 资料来源：[src/core/block-serving.ts:1-70]() ## Configuration ### Retrieval Configuration | Parameter | Default | Description | |-----------|---------|-------------| | `highConfidenceThreshold` | 0.7 | Minimum probability for auto-injection | | `maxHits` | 5 | Maximum blocks per retrieval | | `candidateLimit` | 50 | Initial candidate pool size | ### Output Configuration | Parameter | Default | Description | |-----------|---------|-------------| | `format` | "markdown" | Output format (markdown/xml/silent) | | `audit` | false | Include evidence traces | | `wrapImported` | true | Tag imported fixes | ## Quick Start ```bash # Initialize TraceBase in a project npx tracebase-ai init # This creates a link between the project and the workspace # allowing the SDK to track and retrieve project-specific memory ``` After initialization, the SDK automatically: 1. Detects agent sessions in the project 2. Retrieves relevant memory on each prompt 3. Injects formatted context into the agent's context window 资料来源：[www/src/components/dashboard/OverviewView.tsx:1-30]() ## Memory Funnel The SDK tracks the effectiveness of memory retrieval through a funnel: | Stage | Metric | Description | |-------|--------|-------------| | 1 | `eligibleRuns` | Tasks where TraceBase checked memory | | 2 | `recalledRuns` | Tasks with at least one relevant memory match | | 3 | `injectedRuns` | Memories actually added to context | | 4 | `usedRuns` | Agent actions influenced by memory | This funnel helps measure the realized cost savings from memory injection. 资料来源：[www/src/components/dashboard/ImpactView.tsx:1-60]() --- ## Agent Adapters ### 相关页面 相关主题：[SDK Reference](#sdk-reference)
相关源码文件 以下源码文件用于生成本页说明： - [src/cli/install-targets.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/install-targets.ts) - [src/server/mcp.ts](https://github.com/64envy64/tracebase/blob/main/src/server/mcp.ts) - [src/server/http.ts](https://github.com/64envy64/tracebase/blob/main/src/server/http.ts) - [AGENTS.md](https://github.com/64envy64/tracebase/blob/main/AGENTS.md) - [CLAUDE.md](https://github.com/64envy64/tracebase/blob/main/CLAUDE.md) - [src/cli/hook-self-heal.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/hook-self-heal.ts) - [src/cli/commands/doctor.ts](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts)
# Agent Adapters Agent Adapters are the integration layer that enables TraceBase to communicate with and capture context from various AI coding agents (Claude Code, Cursor, Codex). They handle agent detection, configuration management, memory injection, and hook registration across different agent ecosystems. ## Overview TraceBase supports multiple AI coding agents through a unified adapter system. Each adapter translates between TraceBase's internal abstractions and the agent's specific configuration formats, hooks, and communication protocols. The adapter system handles: - **Agent Detection**: Automatically identifying which agent is running - **Configuration Management**: Writing agent-specific configuration files - **MCP Server Integration**: Registering TraceBase as an MCP server for each agent - **Hook Management**: Installing and maintaining agent hooks for memory capture and injection - **Instruction Injection**: Providing agent-specific instruction files (CLAUDE.md, cursor rules, etc.) ## Supported Agents TraceBase currently supports three major AI coding agents: | Agent | Identifier | Detection Heuristics | Configuration Location | |-------|------------|---------------------|------------------------| | Claude Code | `claude-code` | Environment variables or project files | `.claude/settings.json`, `CLAUDE.md` | | Cursor | `cursor` | Environment variables or terminal program | `cursor.md`, MCP registry | | Codex | `codex` | Environment variables or CLI availability | MCP registry | ## Agent Detection Logic Agent detection occurs through two complementary strategies: environment-based detection and project-based detection. ### Environment-Based Detection The `detectAgentFromEnvironment()` function examines process environment variables to identify the active agent: ```typescript function detectAgentFromEnvironment(): InstallAgent | null { // Codex detection if ( (process.env.CODEX_SHELL === "1" || process.env.CODEX_CI === "1" || process.env.CODEX_THREAD_ID) && isCommandAvailable("codex", ["--version"]) ) { return "codex"; } // Cursor detection if ( process.env.CURSOR_TRACE_ID || process.env.CURSOR_AGENT || process.env.TERM_PROGRAM?.toLowerCase() === "cursor" ) { return "cursor"; } // Claude Code detection if ( process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_DESKTOP ) { return "claude-code"; } return null; } ``` 资料来源：[src/cli/install-targets.ts:38-58](https://github.com/64envy64/tracebase/blob/main/src/cli/install-targets.ts) ### Project-Based Detection The `detectAgentFromProject()` function inspects project files to determine which agent owns the project: ```typescript function detectAgentFromProject(basePath: string): InstallAgent | null { if ( existsSync(join(basePath, ".claude", "settings.json")) || existsSync(join(basePath, "CLAUDE.md")) ) { return "claude-code"; } return null; } ``` 资料来源：[src/cli/install-targets.ts:60-67](https://github.com/64envy64/tracebase/blob/main/src/cli/install-targets.ts) ### Detection Priority ```mermaid graph TD A[Start Detection] --> B{Environment Variables Present?} B -->|Yes| C{Check CODEX_*} C -->|Found| D[Return: codex] C -->|Not Found| E{Check CURSOR_*} E -->|Found| F[Return: cursor] E -->|Not Found| G{Check CLAUDE_*} G -->|Found| H[Return: claude-code] G -->|Not Found| I[Return: null] B -->|No| J{Check Project Files} J -->|Found .claude/settings.json| H J -->|Found CLAUDE.md| H J -->|Neither Found| I ``` ## Configuration Files Each agent uses different configuration mechanisms that the adapter system must manage. ### Claude Code Configuration Claude Code uses: | File | Purpose | Adapter Responsibility | |------|---------|------------------------| | `.claude/settings.json` | Hook configuration | Install and self-heal hooks | | `CLAUDE.md` | Agent instructions | Append managed instruction block | ```typescript // Hook configuration structure in Claude Code interface ClaudeHookConfig { hooks: { [eventName: HookEventName]: string | string[]; }; } ``` ### Cursor Configuration Cursor uses: | File | Purpose | Adapter Responsibility | |------|---------|------------------------| | `cursor.md` | Agent rules | Write agent-specific instructions | | MCP Registry | Server registration | Register tracebase MCP server | The adapter writes Cursor instructions via: ```typescript export function writeAgentsMarkdown(basePath: string): StepResult { return writeAgentInstructionFile(basePath, "cursor"); } ``` 资料来源：[src/cli/install-targets.ts:27-29](https://github.com/64envy64/tracebase/blob/main/src/cli/install-targets.ts) ### Codex Configuration Codex uses MCP (Model Context Protocol) exclusively: ```typescript // MCP configuration structure for Codex interface McpConfig { mcpServers: { tracebase: { command: string; args: string[]; }; }; } ``` ## MCP Server Integration The MCP (Model Context Protocol) server provides a standardized communication channel between TraceBase and supported agents. ### Server Architecture ```mermaid graph LR A[Agent] -->|MCP Protocol| B[tracebase-ai serve --mcp] B --> C[MCP Handler] C --> D[Block Serving] C --> E[Fact Retrieval] C --> F[Memory Injection] D --> G[Knowledge Base] E --> G F --> H[Agent Context] ``` ### Server Startup The MCP server is started via: ```bash npx -y tracebase-ai@latest serve --mcp ``` For Claude Code specifically, the adapter invokes: ```bash claude mcp add tracebase --scope local -- npx -y tracebase-ai@latest serve --mcp ``` 资料来源：[src/cli/commands/doctor.ts:120-122](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ### MCP Health Checks The `doctor` command validates MCP configuration for each agent: ```typescript const mcpInspection = inspectMcpConfig(projectRoot, agent); if (!mcpInspection.present) { checks.push({ name: mcpCheckName, level: "warn", message: `${getAgentTargetMeta(agent).mcpLocationLabel} is missing`, fix: `Run \`${initCommand}\` to register the MCP server.`, }); } else if (!mcp.canonical) { checks.push({ name: mcpCheckName, level: "warn", message: "tracebase MCP entry has a non-canonical shape", fix: `Re-run \`${initCommand} --force\` to reset.`, }); } ``` 资料来源：[src/cli/commands/doctor.ts:124-144](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Hook System The hook system enables agents to capture memory context at specific lifecycle events. ### Supported Hook Events | Event | Trigger | Purpose | |-------|---------|--------| | `PostToolUse` | After tool execution | Capture memory-worthy actions | | `Stop` | Session end | Finalize memory capture | | `Background` | Periodic background | Ongoing context monitoring | ### Hook Self-Healing The adapter includes a self-healing mechanism to maintain hook integrity: ```typescript const HEALTH_FILE_REL = ".tracebase/hook-health.json"; const DEFAULT_THROTTLE_MS = 24 * 60 * 60 * 1000; // 24 hours ``` The self-heal system: 1. Checks hook health on each `init` run 2. Compares current config against expected state 3. Repairs missing or corrupted hooks 4. Preserves user customizations (entries not managed by TraceBase) 5. Never modifies foreign hooks (entries not from TraceBase) 资料来源：[src/cli/hook-self-heal.ts:1-37](https://github.com/64envy64/tracebase/blob/main/src/cli/hook-self-heal.ts) ### Hook Validation The `doctor` command validates hook health: ```typescript const hookInspection = inspectAgentHookConfig(projectRoot, agent); if (hookInspection.supported) { const managedEvents = hookEventsForAgent(agent); const states = managedEvents.map( (e) => [e, hookInspection.events[e] ?? "missing"] as const, ); const missing = states.filter(([, s]) => s === "missing"); // Report missing hooks as warnings if (missing.length > 0) { checks.push({ name: `${agent}-hooks`, level: "warn", message: `Missing hooks: ${missing.map(([e]) => e).join(", ")}`, }); } } ``` 资料来源：[src/cli/commands/doctor.ts:70-95](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Instruction File Management Agent adapters write instruction files that guide agent behavior with TraceBase integration. ### Claude Code Instructions (CLAUDE.md) The adapter appends a managed block to `CLAUDE.md`: ```markdown ... managed instructions ... ``` ### Cursor Instructions (cursor.md) Similar management for Cursor's instruction file. ### Validation The `doctor` command validates instruction files: ```typescript if (!instruction.present) { checks.push({ name: instructionCheckName, level: "warn", message: `${instructionFile} is missing`, fix: `Run \`${initCommand}\` to create the instruction block.`, }); } else if (!instruction.managed) { checks.push({ name: instructionCheckName, level: "warn", message: `${instructionFile} exists but the managed section is missing`, fix: `Re-run \`${initCommand}\` to append the managed block.`, }); } ``` 资料来源：[src/cli/commands/doctor.ts:44-63](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/doctor.ts) ## Installation Flow ```mermaid sequenceDiagram participant User participant CLI participant Adapter participant Agent User->>CLI: tracebase init CLI->>Adapter: detectAgent() Adapter->>Adapter: detectAgentFromEnvironment() Adapter->>Adapter: detectAgentFromProject() Adapter->>Agent: getAgentTargetMeta(agent) alt Agent is Claude Code Adapter->>Agent: Write .claude/settings.json hooks Adapter->>Agent: Append to CLAUDE.md Adapter->>Agent: Register MCP via claude mcp add else Agent is Cursor Adapter->>Agent: Write cursor.md rules Adapter->>Agent: Register MCP else Agent is Codex Adapter->>Agent: Register MCP end Adapter->>Adapter: Self-heal hooks CLI->>User: Installation complete ``` ## Configuration Options ### Init Command Options ```typescript interface InitOptions { path: string; // Project root (default: cwd) agent?: InstallAgent; // Force specific agent apiUrl?: string; // TraceBase API URL apiKey?: string; // Workspace API key force?: boolean; // Overwrite existing config dryRun?: boolean; // Preview changes (deprecated) } ``` ### Agent Meta Configuration Each agent has metadata defining its configuration locations: ```typescript const AGENT_TARGETS: Record = { "claude-code": { mcpLocation: ".claude/settings.json", mcpLocationLabel: ".claude/settings.json", instructionFile: "CLAUDE.md", hooksSupported: true, hookSpec: "inline", }, "cursor": { mcpLocation: "cursor.md", mcpLocationLabel: "cursor rules", instructionFile: "cursor.md", hooksSupported: false, hookSpec: "none", }, "codex": { mcpLocation: ".codex.json", mcpLocationLabel: ".codex.json", instructionFile: null, hooksSupported: false, hookSpec: "none", }, }; ``` ## Error Handling ### Missing Configuration When MCP configuration is missing: ```typescript checks.push({ name: mcpCheckName, level: missingConfigSurface ? "warn" : "fail", message: `${getAgentTargetMeta(agent).mcpLocationLabel} is missing`, fix: `Run \`${initCommand}\` (${displayName} will not see TraceBase until then).`, }); ``` ### Non-Canonical Configuration When an MCP entry exists but has unexpected structure: ```typescript checks.push({ name: mcpCheckName, level: "warn", message: "tracebase MCP entry has a non-canonical shape", fix: `Re-run \`${initCommand} --force\` to reset to the canonical entry.`, }); ``` ## CLI Commands ### `tracebase init` Primary installation command. Auto-detects agent and configures all necessary integrations. ```bash tracebase init [options] ``` | Option | Description | |--------|-------------| | `-p, --path ` | Project root directory | | `-a, --agent ` | Force specific agent | | `--api-url ` | TraceBase API URL | | `--api-key ` | Workspace API key | | `--force` | Overwrite existing config | ### `tracebase doctor` Diagnostic command that validates adapter configuration: ```bash tracebase doctor [options] ``` Validates: - Instruction file presence and managed section - Hook configuration (for supported agents) - MCP server registration ### `tracebase setup` Legacy alias for `tracebase init` for backward compatibility. ```bash tracebase setup [options] ``` 资料来源：[src/cli/commands/setup.ts:1-20](https://github.com/64envy64/tracebase/blob/main/src/cli/commands/setup.ts) ## Summary Agent Adapters form the abstraction layer that enables TraceBase to integrate with multiple AI coding agents through a consistent interface. The system: 1. **Detects agents** through environment variables and project files 2. **Configures agents** with agent-specific file formats and locations 3. **Registers MCP servers** for standardized communication 4. **Manages hooks** with self-healing capabilities 5. **Validates installations** via the `doctor` command The adapter architecture allows TraceBase to remain agent-agnostic at its core while supporting the unique configuration mechanisms of Claude Code, Cursor, and Codex. --- --- ## Doramagic 踩坑日志 项目：64envy64/tracebase 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:1203006515 | https://github.com/64envy64/tracebase | host_targets=mcp_host, claude, chatgpt ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1203006515 | https://github.com/64envy64/tracebase | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | last_activity_observed missing ## 4. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1203006515 | https://github.com/64envy64/tracebase | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1203006515 | https://github.com/64envy64/tracebase | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1203006515 | https://github.com/64envy64/tracebase | release_recency=unknown