berry

Berry provides a workflow for collecting evidence and detecting hallucinations during AI runs.

Typical Workflow:

1. Start a run: Use start_run(problem_statement, deliverable) to create a run with anchor spans (S0 for the problem, S1 for the deliverable).
2. Gather evidence:
   • add_span(text): Add raw text as evidence.
   • add_file_span(path, start_line, end_line): Capture specific file excerpts.
   • distill_span(parent_sid, pattern): Extract key lines from larger spans.
3. Verify claims: Use detect_hallucination or audit_trace_budget to check if answers are supported by the gathered evidence.

Berry implements a safety model to restrict tool capabilities:

• File Access: The add_file_span tool respects allowed_roots and the project root. If no project root is configured and allowed_roots is empty, file reads fail closed (access is denied).
• Permissions: Configuration options like allow_write, allow_exec, and allow_web control tool expansions.
• Write Restrictions: When writes are enabled, paths must reside within the repository root or an explicitly allowed root.

Berry measures grounding by calculating the information sufficiency of cited evidence for each claim using an information-budget test.

The Process:

1. Input: An answer and the cited evidence spans.
2. Decomposition: The answer is split into individual claims.
3. Evidence Resolution: Evidence is resolved from a server-owned, tamper-evident span ledger.
4. Scoring: Each claim is scored using token logprobs (EDFL) to determine the 'budget gap'.
5. Decision:
   • A negative budget gap means the evidence carries the claim (PASS/grounded).
   • A positive budget gap (exceeding a target) means the evidence does not support the claim (FLAG/unsupported).

All decisions are recorded in a hash-chained, tamper-evident SQLite ledger for auditing.

The Berry installer is designed to be safe and idempotent:

• Idempotent Markdown Writes: Berry-owned Markdown sections are bounded by <!-- berry:install:start --> and <!-- berry:install:end -->. Repeated installs replace old sections rather than appending duplicates.
• JSON Integrity: JSON writes preserve unrelated keys and fail closed on invalid JSON (unless --force is used).
• Atomic Text Writes: Text files are updated using an atomic temporary-file replace to prevent corruption.
• Dry Runs: Use --dry-run to preview changes before they are applied to the filesystem.

Each Berry run generates an auditable artifact located at ~/.berry/runs/<id>/. This directory contains:

• run.sqlite: The source of truth containing spans, claims, audits, and hash-chained events.
• ledger_events.jsonl: An append-only event log.
• run.json, *.tsv: Inspection exports for evidence, attempts, claims, and audits.

The SQLite ledger uses incremental, hash-chained writes. If any row, metadata, or chain mismatch is detected during loading, the system fails closed to ensure integrity.

Berry determines the project scope using the following logic:

1. Uses the directory provided via the --project-root flag if present.
2. Otherwise, walks up from the current working directory to find a .git directory.

Note: If no .git directory is found, Berry will fail closed. To allow using the current directory as the project scope without a .git folder, set the environment variable BERRY_ALLOW_NON_GIT_ROOT=1.

After running berry init, you can connect clients using the generated configuration files. You can also print specific configurations or use deep-links for certain IDEs.

Clients supported via print-config:

• cursor
• codex
• claude
• gemini

# Print configs on demand
berry print-config cursor
berry print-config codex
berry print-config claude
berry print-config gemini

# Cursor deep-link (installs in Cursor directly)
berry deeplink cursor

# View setup hints
berry instructions

By default, berry install writes to user-profile artifacts. To install Berry into the current repository instead, use the --project flag.

Note: Project installs require a git repository by default. If you need to install into a non-git directory, use the --project-root PATH flag or set the environment variable BERRY_ALLOW_NON_GIT_ROOT=1.

berry install --project --platform codex
berry cursor install --project
berry gemini install --project

For high-trust verification, use the run-scoped _run variants instead of legacy raw-span verifiers. These tools resolve [S#] citations directly from the server-owned run ledger, preventing the agent from supplying arbitrary (and potentially untrusted) span text.

Recommended Tools

• detect_hallucination_run(answer, run_id?, ...)
• audit_trace_budget_run(steps, run_id?, ...)

Verification Rejections

The server will reject evidence packs containing:

• Unknown SIDs
• anchor, assumption, decision, or audit spans
• stale, tombstoned, redacted, or quarantined spans
• secret or PII spans (unless allow_sensitive=true)
• untrusted or quarantined spans (unless allow_untrusted=true)
• Non-extractive derived summaries
• Spans that exceed the prompt budget

Berry uses an evidence-based execution model to ensure LLM reliability by enforcing verification at the MCP tool boundary.

Managing Runs and Evidence

• start_run: Anchors a specific problem statement and a target deliverable. A run consists of multiple 'spans' that collect evidence.
• add_span: Adds a new piece of evidence to the current run.
• add_file_span: Specifically adds file-based evidence to a run.
• distill_span: Processes or refines a span to build trusted evidence.

Navigating Evidence

• list_spans: Lists all spans within a run.
• get_span: Retrieves a specific span.
• search_spans: Searches through collected evidence spans.