Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions IMPLEMENTATION-PROPOSAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -619,12 +619,13 @@ agent-trajectories/

```
.trajectories/
├── index.json # Quick lookup index
├── active/
│ └── traj_abc123.json
│ └── traj_abc123/
│ └── trajectory.json
├── completed/
│ └── 2024-01/
│ └── traj_def456.json
│ └── traj_def456/
│ └── trajectory.json
└── archive/
```

Expand All @@ -633,11 +634,12 @@ agent-trajectories/
- Git-friendly (version with code)
- Human-readable/editable
- Works everywhere
- No shared mutable index file to merge

**Cons:**
- No efficient querying
- No full-text search
- Index can get out of sync
- Directory scans may become expensive at very large scales
- Large repos = slow listing

**Best for:** Simple setups, single-agent use, git-centric workflows
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,14 @@ trail compact --commits abc1234,def5678 # Trajectories matching specific commit
trail compact --pr 123 # Trajectories mentioning PR #123
trail compact --since 7d # Last 7 days
trail compact --all # Everything (including previously compacted)
trail compact --pr 123 --discard-sources # Delete source trajectories and update index after compaction
trail compact --pr 123 --discard-sources # Delete source trajectories after compaction
```

### Automatic Compaction (GitHub Action)

Add these steps to any workflow that runs on PR merge (e.g., your release or publish flow). Requires `ref: ${{ github.event.pull_request.base.ref }}` and `fetch-depth: 0` on checkout, plus `contents: write` permission.

Use `--discard-sources` when the compacted summary should replace the raw source trajectories. This removes the source JSON/Markdown/trace files and updates `.trajectories/index.json`, reducing future list/search noise.
Use `--discard-sources` when the compacted summary should replace the raw source trajectories. This removes the source JSON/Markdown/trace files, reducing future list/search noise.

```yaml
- name: Compact trajectories
Expand Down
35 changes: 12 additions & 23 deletions docs/architecture/core.md
Original file line number Diff line number Diff line change
Expand Up @@ -309,29 +309,17 @@ Recommend users add to `.gitignore`:

## Performance Considerations

### Index for Fast Lookups

Maintain `index.json` for quick listing without reading all files:

```json
{
"version": 1,
"lastUpdated": "2024-01-15T10:00:00Z",
"trajectories": {
"traj_abc123": {
"title": "Implement auth",
"status": "completed",
"startedAt": "2024-01-15T08:00:00Z",
"completedAt": "2024-01-15T10:00:00Z"
}
}
}
```
### Directory Scans for Lookups

List and search commands scan per-trajectory files under `active/` and
`completed/`. Keeping each trajectory in its own directory avoids a shared
mutable index file and reduces merge conflicts when multiple branches add
trajectories.

### Lazy Loading

Only load full trajectory data when needed:
- `list` command reads only index
- `list` command scans trajectory files and reads summary metadata
- `show` command loads full trajectory
- `search` may need to load all (acceptable for v1, optimize later with SQLite)

Expand All @@ -347,13 +335,14 @@ Warn users if trajectory exceeds reasonable size:

```
.trajectories/
├── index.json # Quick lookup index
├── active/ # In-progress trajectories
│ └── traj_abc123.json
│ └── traj_abc123/
│ └── trajectory.json
├── completed/ # Finished trajectories
│ └── 2024-01/ # Organized by month
│ ├── traj_def456.json
│ └── traj_def456.md # Auto-generated markdown
│ └── traj_def456/
│ ├── trajectory.json
│ └── summary.md # Auto-generated markdown
└── .gitignore # Ignore active/, keep completed/
```

Expand Down
9 changes: 4 additions & 5 deletions docs/trail-snippet.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,17 +83,16 @@ trail complete --summary "Added JWT auth with refresh tokens" --confidence 0.85

After completing work, compact the finished trajectory or merged PR into a
durable summary. When the compacted summary is sufficient, discard the raw
source trajectories so `.trajectories/index.json` and list output stay focused:
source trajectories so list output stays focused:

```bash
trail compact --discard-sources
# or after a PR merge:
trail compact --pr 42 --discard-sources
```

`--discard-sources` removes the source trajectory JSON/Markdown/trace files and
updates the index. Use it after confirming the compacted artifact is the record
you want to keep.
`--discard-sources` removes the source trajectory JSON/Markdown/trace files. Use
it after confirming the compacted artifact is the record you want to keep.

**Confidence levels:**
- 0.9+ : High confidence, well-tested
Expand Down Expand Up @@ -154,7 +153,7 @@ trail compact --commits abc123,def456 --discard-sources

Compaction consolidates decisions and creates a grouped summary. Adding
`--discard-sources` makes the compacted artifact the durable record by removing
the raw trajectories and their index entries.
the raw trajectories.

## Why Trail?

Expand Down
4 changes: 1 addition & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,7 @@
"type": "git",
"url": "https://github.com/AgentWorkforce/trajectories"
},
"files": [
"dist"
],
"files": ["dist"],
"engines": {
"node": ">=20.0.0"
},
Expand Down
Loading
Loading