Learnings

Your agent forgets everything when a session ends. Trail-code keeps what your agent works out as learnings, saved from your conversations as you work. The next session starts from what you, your agents and your team already know. You don’t have to write any of it by hand.

Four kinds, three places

Every learning has a kind (what it is) and a place (who it is for).

Three places: personal (about you and your machine, in ~/.trail/, only you see it), repo (about the code, in the repo’s .trail/, committed with the change), and team (what your whole team has learned across repos, in a Trail workspace, coming soon).

Your agent picks between personal and repo: something about your own setup stays personal (“saved just for you”); something about the code goes in the repo (“added to this repo”). The team place will gather the repo learnings of every repo in your workspace, so your team sees them together.

Four kinds: decisions (why the code is the way it is), preferences (how you like things done), skills (how a job is done here), and guardrails (what must never happen). Decisions and preferences ship today; skills, guardrails and the team place are coming soon. Preferences are saved when you correct your agent, and found in your past sessions by trail init. Guardrails will be checked before the command runs.

See the full tables in Learning file format.

Your agent does the saving

Your agent uses learnings on its own, and saves one when you ask, at these moments:

On day one, what you told Claude before. trail init reads your own messages in the repo’s past Claude Code sessions, leaving out tool output, pasted text and headless runs. It keeps only what you said in two or more sessions, and scrubs secrets.
When you ask, a learning. Say “save this as a learning” after a decision, something you ruled out, or a correction to how something is done here, and your agent saves it: what was decided, what was ruled out, what to watch out for. A summary, never a transcript, and nothing secret. It never saves one on its own, and doesn’t offer to.
Before each task, the learnings on it. Each session starts with the learnings that apply to all work in the repo. Each prompt brings in the ones earlier sessions left on that code, above the code itself. A teammate’s learning says whose it is.
Before a PR, the check. Your agent is told to run trail check before it commits, pushes or opens a pull request.
Never rewrites history. Your agent never edits an existing learning. When it goes against one, it says why in the commit, and saves a new one only when you say so.

A learning is a file

A decision is a short markdown file in .trail/learnings/, reviewed in the pull request like any other change. Its touches field is how the next session on that code finds it. A learning also records what the session spent working it out, in minutes and tokens. That is where “saved ~27k tokens” comes from: what the learning took to work out, less what it costs to read.

Because a repo learning is a file in your pull request, a wrong one gets reviewed like the code it is about. Delete or edit the file to drop it.

One decision, two teammates

A real test: two people, two clones of hashicorp/go-retryablehttp, headless Claude Code sessions.

1. Maya works out why the retry count is 4. Before committing, the agent saves what it found as a learning, and commits it with the change:

✓ added to this repo · .trail/learnings/2026-10-09-keep-the-default-retry-count-at-maya.md

The reply ends with 📝 Committed · Kumar works in this part of the codebase, and their agents now get a 27k-token head start.

2. Kumar pulls and asks about the same code. Kumar’s Claude reads Maya’s learning before exploring, answers from it in 11 seconds for $0.10, and ends with a line saying where the answer came from, like:

📝 Started from Maya's learning · saved ~27k tokens

3. Kumar raises the retry count to 10 anyway. Before the PR, trail check compares the change with the learnings in the repo, and Kumar’s own:

checking 1 changed file against 1 learning and 0 skills

✗ client.go:51
  changes defaultRetryMax from 4 to 10
  Maya · Oct 9: Keep defaultRetryMax = 4: ten retries with the
  default backoff can hold one Do() call for over an hour.

· 1 conflict · fix it, or say why in the commit message or PR description

Kumar’s Claude explains the override in the commit.

4. Maya edits the same constant. Kumar’s branch isn’t merged yet. Right after the edit, Maya’s Claude reads Kumar’s change and says something like:

🔀 trail · Kumar is also changing defaultRetryMax on kumar/retry. He raises it to 10 and you're lowering it, so the two clash.

None of this needs a server. Learnings travel through git, like the code they are about.