Skip to main content

ragtrail

Reuse the retrieval paths your agent already solved.

ragtrail is a trajectory cache for agentic RAG. It records the path an agent took to a cited answer (the searches it ran, the nodes it opened, the ones it cited) and hands that path back when a similar question arrives, so the agent skips the orientation phase. Paths are invalidated by content hash when the underlying nodes change.

It caches the path, never the answer.

CI

Status: alpha (0.1.0, not on PyPI yet). The core, the MCP server and the evaluation harness work and are tested; the cloud stores in PLAN.md (M6–M8) are not built. The public API may change between 0.x releases. Write-up: Building ragtrail.

Install

pip install 'git+https://github.com/aralde/ragtrail.git'            # core: stdlib + sqlite3 + pydantic
pip install 'ragtrail[mcp,embed] @ git+https://github.com/aralde/ragtrail.git'   # MCP server, embedding matcher

Python 3.11 or newer.

Use it from Python

Wrap one agent turn. On entry you get the recalled path (if any); on exit an accepted turn is stored.

from ragtrail import GenericResolver, SQLiteStore, turn
from ragtrail.resolver import text_hash

resolver = GenericResolver(
    hash_fn=lambda node_id: text_hash(docs[node_id]) if node_id in docs else None,  # None = deleted
    read_fn=lambda node_id, max_tokens: docs[node_id],
)

with SQLiteStore("trails.db") as store:
    with turn(store, resolver, scope="my-team", query=question) as t:
        if t.recall.mode != "miss":
            print(t.recall.rendered)  # nodes to start from, or their current text
        # ... run your agent, record what it did and what it cited ...
        t.step("search", {"query": question}, found_ids)
        t.cite(cited_ids)
        t.accept("verified")  # no accept, no trail

A runnable version over plain chunk ids is in examples/chunk_rag.py; the subforest one is examples/subforest_rag.py.

How it works

  1. Match. The question is normalized and matched against stored questions with MinHash/LSH (stdlib only), or by embeddings if you enable them. Lookup is a handful of key reads, so any key-value store can back it.
  2. Validate. Every cited node is re-hashed against the live index. All unchanged: prefetch (current node text, within a token budget). Some changed: hint with only the still-valid nodes. All changed: miss, and the trail is marked stale.
  3. Admit. A trail is written only with a positive signal (verified citations, user feedback, or an explicit accept). Scopes (tenant, document, permission group) never mix.

Design decisions, with the numbers that drove them, are in docs/decisions.md.

Limitations

  • Savings come only from repeated or reworded questions; the evaluation uses model-written repeats, so real traffic will save less.
  • Hash validation catches changed nodes, not new documents that would now be better evidence; only the TTL covers that.
  • Admission quality decides safety. A path from a wrong answer sends the agent back to the same mistake.
  • Evaluated with one agent model (Haiku) and one judge (Sonnet, checked on 40 labels, not human-labelled).
  • The evaluation harness needs subforest and the claude CLI; the library itself does not depend on either.

MCP server

pip install 'ragtrail[mcp]'
ragtrail serve --db trails.db --scope my-team --subforest corpus.db

The server exposes two tools: recall(query, budget_tokens?) at the start of a question and record(query, cited, outcome?, steps?) after a grounded answer. Each server is bound to one --scope.

Add --embed (needs pip install 'ragtrail[embed]') to also match paraphrases by embeddings. It uses a local CPU model, BAAI/bge-small-en-v1.5 by default, so there is no API cost.

How it checks nodes:

  • --subforest corpus.db: a subforest index. Node hashes are checked on every recall and texts are prefetched.
  • --resolver mypkg.index:make_resolver: any NodeResolver for your own index.
  • Neither: unverified mode. Recall only hints node ids and never prefetches.

Claude Code:

claude mcp add ragtrail -- ragtrail serve --db ~/.ragtrail/trails.db --scope my-team --subforest corpus.db

Other MCP clients (Claude Desktop, Cursor, …) use the same command in their JSON config:

{
  "mcpServers": {
    "ragtrail": {
      "command": "ragtrail",
      "args": ["serve", "--db", "/path/to/trails.db", "--scope", "my-team", "--subforest", "/path/to/corpus.db"]
    }
  }
}

Run it next to your retrieval tools (for example subforest's own MCP server). ragtrail purge --db trails.db deletes expired trails.

Evaluation

Summary and details: reports/README.md. Haiku agent and Sonnet judge through claude -p.

Repeat traffic (the same question asked again in other words), all questions, cache off vs on.

The realistic run uses trails the agent recorded itself on WixQA (n = 200):

  • Tool calls: 3.4 → 2.1.
  • Input tokens: −33%.
  • Judged correct: 69.8% → 74.2% (+4.5, 95% CI −0.8 to +9.8): no accuracy loss.

With oracle trails, which cite the gold evidence, the per-hit gains are larger. Treat them as an upper bound:

Dataset n Tool calls Input tokens Judged correct
WixQA help center 200 3.4 → 2.2 −28% 69.8% → 86.2%
QASPER papers 400 4.1 → 1.5 −57% 60.8% → 71.6%
  • Only record trails from answers you trust. When the recorded answer was wrong, warm accuracy fell from 50% to 21% on those questions; when it was right, it rose from 79% to 87%.
  • Put fixed context (document, product, customer) in scope. If a paper's title is part of the matched text, any question about that paper looks similar and gets the wrong sections.
  • Savings come only from repeated questions. Every test question here is a model-written repeat, so the cache saves less on real traffic, where fewer questions repeat. Related work: docs/related-work.

Reproduce (needs subforest installed alongside and the claude CLI; add --dataset qasper for QASPER):

ragtrail eval fetch
ragtrail eval paraphrase
for s in disjoint repeat; do
  ragtrail eval offline --scenario $s && ragtrail eval offline --scenario $s --embed
done
ragtrail eval agent --scenario repeat --n 30 [--embed]    # likewise disjoint with --n 20
ragtrail eval judge --scenario repeat [--embed]
ragtrail eval report

Demos

uv run python examples/demos.py runs six small offline cases, no API needed: paraphrase reuse, an edited source (ragtrail drops it; a copy cache serves the old text), a deleted source, the fixed-context false match and its scope fix, tenant isolation, and admission gating. Pass a name (freshness, fixed-context, ...) to run one.

Development

uv sync --all-extras
uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest

See CONTRIBUTING.md.

License

MIT

Metadata

Release files for ragtrail 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ragtrail 0.1.0
File Size Uploaded Provenance Actions
ragtrail-0.1.0.tar.gz 56.2 kB With provenance Details for ragtrail-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ragtrail 0.1.0
File Interpreter ABI Platform Actions
ragtrail-0.1.0-py3-none-any.whl Python 3 none any Details for ragtrail-0.1.0-py3-none-any.whl

Total release size: 124.6 kB

Release files / ragtrail-0.1.0.tar.gz

Download URL ragtrail-0.1.0.tar.gz
Size 56.2 kB
Tags Source
SHA-256 checksum
How to use checksums
8f3ad63aa121d01037c716b56d8e531e485ad82399337ef479837118db4833fa
BLAKE2b-256 checksum
How to use checksums
7e9c6a669c1b29b0f721c7b918b1505c6cee8e57fbc51bc3e19283b5e19ee057
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / ragtrail-0.1.0-py3-none-any.whl

Download URL ragtrail-0.1.0-py3-none-any.whl
Size 68.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5076b8e8a471820d222bbcd8c075d59fde10e8456a049465a96ff467f2ef04c5
BLAKE2b-256 checksum
How to use checksums
2edc24b53fbf30e3fdcea601d5415bc24801847446624b9f5eb41169d4bcd00e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for ragtrail 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ragtrail-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page