https://github.com/sincerema/sidetrail

SideTrail is an open-source sidecar for AI-powered code tools that preserves long-lived project context outside the codebase. It records decisions, constraints, architecture drift, blast-radius dependencies, and difficulty signals so host agents can act with durable project memory instead of only the current source snapshot.
https://github.com/sincerema/sidetrail

agent-integration ai-assistant knowledge-management project-memory sidecar software-architecture

Last synced: 2 days ago
JSON representation

SideTrail is an open-source sidecar for AI-powered code tools that preserves long-lived project context outside the codebase. It records decisions, constraints, architecture drift, blast-radius dependencies, and difficulty signals so host agents can act with durable project memory instead of only the current source snapshot.

• Host: GitHub
• URL: https://github.com/sincerema/sidetrail
• Owner: SincereMa
• License: mit
• Created: 2026-06-06T06:12:20.000Z (9 days ago)
• Default Branch: main
• Last Pushed: 2026-06-07T12:27:53.000Z (8 days ago)
• Last Synced: 2026-06-07T14:15:25.155Z (8 days ago)
• Topics: agent-integration, ai-assistant, knowledge-management, project-memory, sidecar, software-architecture
• Language: Go
• Homepage:
• Size: 235 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# SideTrail

> A sidecar that gives AI agents long-lived memory of the projects they work on — without modifying them.

Mainstream agents see the current state of a project. The reasoning

that produced that state is lost. The constraints that bind the

project live in the heads of the team, not in the code. The agent

treats every part of the project as equivalent, when in fact some

parts are hard to change safely and some are easy. And when the agent

edits a service, it has no reliable way to see which other services

depend on what it is about to change.

SideTrail is a sidecar that records this missing context —

decisions, constraints, health signals, project state — and makes it

available to the host agent before it acts. It does not touch the

host agent. It does not replace it. It runs alongside it.

## The five gaps

1. **Reasoning trails for project evolution are lost between sessions.**

   > "This area was adjusted three times. The first attempt changed

   > X because of Y. The second attempt found a side effect Z and

   > was rolled back to X. The current state is the result of the

   > third attempt, chosen specifically to avoid Z."

2. **The blast radius of an edit is invisible across services, modules, and subprojects.**

   The agent can see the file it is changing, but not the services,

   modules, subprojects, or shared contracts that depend on that

   file — statically, at runtime, or operationally. Local

   correctness, global regression.

3. **Project difficulty is uneven and shifts, but the agent has no read on it.**

   Some modules are churn hotspots, some are bug clusters, some

   have eroding test coverage, some depend on stale libraries. The

   agent cannot prioritize, warn, slow down, or escalate review

   where it matters.

4. **Documented architecture drifts from actual architecture.**

   > "The architecture diagram shows service A and service B as

   > cleanly separated. Service B has, for the last eight months,

   > been reading service A's primary database directly. Every new

   > feature in B assumes the read. Removing it is a multi-quarter

   > project, not a refactor."

5. **Tribal constraints are nowhere the agent can read them.**

   > "Don't change the code in `legacy/billing/` — there's a

   > compliance review pending."

   >

   > "We use library Z despite its license because alternatives have

   > all been blocked by security."

   >

   > "That migration is paused; do not touch the bridge code until

   > Q3."

The formal definition of each gap — kinds, statuses, sub-cases,

surface mapping, cross-cutting dimensions — is in

[docs/scope.md](docs/scope.md). The non-negotiable principles that

shape how we solve them are in [AGENTS.md](AGENTS.md).

## How it works

SideTrail is a **sidecar**, not a competing agent. It runs

alongside the host agent (Claude Code, Cursor, Aider, …) and

records long-lived context. It does not fork, patch, or inject into

the host.

A few hard constraints shape the design:

- **Non-intrusive.** Observe and record; never edit the host agent.

- **Lightweight.** No heavy runtime, no bundled LLM calls the user

  did not request.

- **Cross-platform and cross-agent.** macOS, Linux, Windows; one

  binary, one config; adding support for a new host agent is a

  localized change.

- **Simple configuration.** Near-zero config to get value;

  everything else opt-in.

The full principle set lives in [AGENTS.md](AGENTS.md).

## Status

Early development. The v0 CLI surface is in place; tagged builds

are published as GitHub releases. The problems the project exists

to address are recorded in [docs/scope.md](docs/scope.md); the

architectural decisions that follow from them live in

[docs/decisions/](docs/decisions/).

## Install

The fastest path is a one-liner. It downloads the latest release

for your OS and architecture, verifies the SHA-256, and drops the

 `sidetrail` binary on disk.

```sh

curl -fsSL https://raw.githubusercontent.com/SincereMa/sidetrail/main/scripts/install.sh | sh

```

On Windows, from PowerShell:

```powershell

iwr https://raw.githubusercontent.com/SincereMa/sidetrail/main/scripts/install.ps1 -useb | iex

```

Both scripts accept flags. See `scripts/install.sh --help` or

`Get-Help ./scripts/install.ps1` for options. The binary lands in

`~/.local/bin` (or `%USERPROFILE%\bin` on Windows) by default; add

that directory to `PATH` if it is not already.

For a pinned version, set `SIDETRAIL_VERSION=v0.1.0` (or pass

`--version` / `-Version`). For a custom install location, set

`SIDETRAIL_INSTALL_DIR` (or pass `--dir` / `-InstallDir`).

If you prefer to install manually, download a release archive from

the [GitHub releases page](https://github.com/SincereMa/sidetrail/releases),

verify it against the matching `*_checksums.txt`, and place the

 `sidetrail` binary anywhere on `PATH`.

## Project layout

| Path | Purpose |

| --- | --- |

| `AGENTS.md` | Mission, principles, and pointers for contributors and host agents. |

| `LICENSE` | MIT license terms. |

| `CODE_OF_CONDUCT.md` | Community expectations. |

| `CONTRIBUTING.md` | How to file issues and submit changes. |

| `docs/scope.md` | The problems SideTrail exists to address; the input to subsequent ADRs. |

| `docs/decisions/` | Architectural decision records. |

| `docs/agents/` | Per-host-agent adapter specifications. |

| `ROADMAP.md` | Implementation status, outstanding tasks, and next milestones. |

## CLI surface

The  `sidetrail` binary is a read-dominant command. Most calls ask a

question; a few write a record. The `.sidetrail/` store is discovered

by walking upward from the current working directory unless

`--root` points elsewhere. The CLI surface has thirteen subcommands:

| Command | Purpose |

| --- | --- |

| `sidetrail add ` | Validate a record file and add it to the store. |

| `sidetrail get  [--human]` | Fetch a record by id (exact, then prefix). |

| `sidetrail list [--kind K] [--limit N] [--json]` | List records, newest first. |

| `sidetrail ask --scope  [--kind] [--tag] [--limit] [--json]` | Query records whose scope matches a pattern. |

| `sidetrail context --file  [--radius N] [--limit] [--json]` | Aggregate records relevant to a file path. |

| `sidetrail verify ` | Refresh a record's `last_verified_at`. |

| `sidetrail supersede  --new ` | Mark a record superseded and add a replacement. |

| `sidetrail init [--root ] [--no-write]` | Seed a `.sidetrail/` store from existing project docs. |

| `sidetrail promote [...] [--all]` | Promote seed records from `_seed/` to the active store. |

| `sidetrail draft  --subject ` | Create a draft record for human review in `_draft/`. |

| `sidetrail status  ` | Transition a record's status. |

| `sidetrail validate ... [--json]` | Validate record files against the schema. |

| `sidetrail health [--json] [--stale-days N]` | Report project health signals and stale records. |

The first host-agent integration point is `sidetrail context`: point

it at the file the agent is about to edit, and it returns the

records the team has filed about that file and its enclosing

scopes.

Adapter guides for specific host agents live in

[docs/agents/](docs/agents/). The first is for

[OpenCode](docs/agents/opencode.md), a model-agnostic coding

agent.

`sidetrail init` is the cold-start path. It scans the canonical

project paths and writes scrape-derived candidate records to

`.sidetrail/_seed/`. Skipping init is valid; the sidecar is usable

from empty.

## Contributing

Issues and pull requests are welcome. Please read

[CONTRIBUTING.md](./CONTRIBUTING.md) and

[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) first.

## License

[MIT](./LICENSE). Copyright (c) 2026 SideTrail Authors.