Most of what Pathrule learns about your project it learns from work, not from writing. When an AI session finishes a piece of work it records a short structured entry, and that single entry is what several other features are built on.

This page is about what is in that entry, what is deliberately left out of it, and what it goes on to power.

## What is recorded

Each entry is a handful of fields, all small:

- **Area, action and scope.** What kind of thing was touched (`ui`, `backend`, `database`, `config`, `test`, `docs`), what was done to it (`create`, `update`, `fix`, `refactor`, `delete`, `style`), and at what level (a component, a page, an API, a migration, a service).
- **Subjects.** Up to five lowercase keywords, the way you would tag the work in conversation.
- **A one-sentence summary.** What changed and why, in a line.
- **The paths it touched**, grouped by area.
- **Which AI client** the session ran in, and when.
- **How the turn went**: how many tool calls it took, how many failed, and a short code for each kind of failure (`timeout`, `exit_nonzero`, `not_found` and similar). Counts and codes only, never the command or the error text.

That is the whole record. It is designed to be readable at a glance months later, which is also why it stays short.

## What is never recorded

Your code is not in it. No file contents, no diffs, no patches, no commit messages, and no prompt text. The paths are there so later features can tell *where* work happened; the substance of the change is not stored.

Paths are also **normalised before they are stored**. A path arrives as whatever the agent saw on that machine and is converted to workspace-relative form, so `/Users/you/projects/app/src/api.ts` becomes `src/api.ts`. Nothing machine-specific reaches shared team knowledge, and the same file is the same file whoever touched it.

## What one entry feeds

The reason the record is worth keeping is what reads it:

- **[Work episodes](/docs/content/work-episodes).** Related entries from one working session roll into a titled record of one thing your team solved, which a later session can recall.
- **[Files that change together](/docs/retrieval/co-change).** The paths in each entry are what teaches Pathrule which files travel in pairs.
- **Retrieval learning.** When knowledge was put in front of an agent and the agent then worked in that same area, that is evidence the knowledge was relevant. Over time it moves the ranking, described in [how retrieval works](/docs/retrieval/how-retrieval-works).
- **[Staleness suggestions](/docs/content/suggestions).** Recent activity against a path is one of the signals that a memory referencing that path may have drifted.

None of those needs a separate step from you. They all come from the same short entry.

## Logging never blocks the work

One deliberate design choice is worth calling out, because it shows up in how the tool behaves. **Logging never fails for size.** If a summary runs long or a task touched dozens of files, the entry is trimmed on the server and stored, rather than rejected.

Rejecting it would be worse than trimming it. An agent that gets a validation error reads it as "fix the arguments and try again", and spends the next several turns rewriting a summary instead of finishing your task. So the limits are applied quietly, on the way in, and the response tells the agent what was stored.

## What the failure counts are used for

The tool-call and failure counts are how Pathrule answers "which files does this codebase make an assistant struggle in" from real work rather than from opinion. Two things read them.

The first is a weekly grouping. Every failure is recorded as a triple: the kind of tool, the file it was working on, and a short code for how it failed. Grouped by week, that turns into a plain list of the files an assistant fails in most often, and what kind of failure it hits there. A file that shows up repeatedly under `file_not_found` is usually a stale path in your own docs or a moved module nothing updated. One under `syntax_error` is usually a file that is hard to edit safely.

The second is retrieval learning. If a turn received knowledge from Pathrule and still ran into tool failures, the knowledge it was given takes a small negative signal, weighted by how bad the failure was. Permission, token-limit and rate-limit failures count more heavily than an ordinary miss. That signal joins the same learning loop described in [what makes knowledge rank higher](/docs/retrieval/how-retrieval-works), so knowledge that keeps showing up in turns that go badly gradually stops being chosen.

## What a failure count can and cannot see

This depends on the assistant you use, and the honest answer is not uniform.

File tools report properly. A failed read, edit or write arrives with its message, so it is classified and attributed to the right file. That is the case worth having, because a file path is what makes the number actionable.

Shell exit status often does not. Some assistants do not report a non-zero exit code at all: a command that fails and one that succeeds arrive looking identical. Pathrule does not guess. It records what the assistant actually reported and classifies the rest as unknown rather than inventing a failure, because a wrong failure attached to a file is worse than a missing one.

## Access and scope

Entries live in the workspace they were recorded in, behind the same per-user access control as memories, rules and skills. A teammate sees the activity for workspaces they can already see, and nothing else. Retention follows your plan, and the oldest entries age out on a schedule rather than accumulating forever.