Skopos

An experimental, local profiler of how software agents acquire project knowledge. Skopos imports observations, preserves their provenance, and reports the files, ranges, rereads, and associations worth investigating. It does not yet demonstrate that any proposed memory optimization improves task outcomes. §GRUND-skopos

Try the prototype

Requires Rust 1.85 or newer. SQLite is bundled; no database server or API key is needed. From a checkout:

cargo run -- import-pi examples/pi-session.jsonl \
  --repository demo --revision demo-rev --run demo --complete
cargo run -- report demo
cargo run -- related docs/spec.md --repository demo --revision demo-rev

The synthetic example produces six reads, one identical reread candidate, one unsupported shell result, and two context epochs. Its two samples belong to one task: they are not two independent trials. No synthetic source text or prompt content enters the ledger. §FS-pi.2 §FS-analysis.1 §FS-analysis.2

All commands print JSON. The default database is .skopos/ledger.sqlite3, ignored by Git. Use global --db PATH to choose another ledger. Reimporting an identical snapshot is safe and adds no duplicate events. §FS-ledger.1 §FS-ledger.2

What is implemented

• Transactional import of the closed skopos.event.v1 JSONL contract.
• A Pi v3 transcript adapter with explicit branch selection, tool-call/result pairing, conservative compaction boundaries, and coverage-gap counts.
• reads, report (also files), compare, and status commands.
• Revision-scoped related and graph reports: support, distinct-task support, conditional probability, Jaccard, lift, and next-recorded-step probability.
• Separate agent/session/model/epoch samples, optional requested/delivered ranges and Grund section references, and explicit provenance and missing values.
• An end-of-task feedback prompt and split-candidates report for agent-nominated unused spans, kept separate from measured reads. §FS-feedback

The behavior is specified in requirements.md. §FS-events §FS-pi §FS-ledger §FS-analysis

Import a real snapshot

cargo run -- import-pi /path/to/frozen-session.jsonl \
  --repository agent-grounds/example --revision COMMIT_AT_RUN_TIME \
  --run rhei-invocation-id --task rhei-task-id --complete
cargo run -- reads rhei-invocation-id
cargo run -- compare first-run second-run

Supply the historical revision, not today's checkout revision. --leaf ENTRY_ID selects a particular branch; otherwise the last entry's ancestry is selected. Use a new run ID for a different snapshot. Omit --complete when the snapshot is partial; EOF does not establish completion. The importer never follows a parent session path or opens source files from the current checkout. §FS-pi.1 §FS-pi.3

For other runtimes, produce normalized event JSONL and use skopos import FILE or skopos import -. Existing Rhei IDs can be preserved for later accounting joins. Native Rhei accounting import is planned, not implemented. §FS-events.1 §FS-ledger.2

How to interpret results

Agents can nominate up to five spans they believe they read without using. Collect these with the end-of-task prompt, then join the response sidecar to recorded reads:

cargo run -- split-candidates /path/to/feedback.jsonl \
  --repository agent-grounds/example --revision COMMIT_AT_RUN_TIME

The report ranks exact file/range matches by distinct-task support and agent priority. It distinguishes known delivered spans from requested or unverified coordinates, preserves confidence and reasons, and accepts an empty response. Use repeated nominations to investigate file or chapter splits, not to delete content or claim savings. No agent is contacted automatically. §FS-feedback.3

A native transcript establishes recorded tool output. It does not establish final model submission, retention after compaction, attention, necessity, or causal use. Pi imports therefore retain requested ranges but leave exact delivered source ranges unknown. Auto-loaded instructions, summaries, images, and arbitrary shell/search output are outside this adapter's read coverage. §FS-pi.2 §GRUND-skopos.1

Identical reread candidates mean repeated returned text in the same agent context, with edits and context resets accounted for. They may be necessary. Reported bytes and optional token estimates are not total provider usage, billing, or proven savings. Co-reading is neither dependency nor proof that preloading the pair helps. Minimum support defaults to two samples; inspect distinct task support and validate on held-out tasks. §FS-analysis

The prototype loads the ledger into memory and computes pairwise associations; it is intended for small evaluation corpora. It has no daemon, live capture, automatic memory edits, or context injection. Normalized records are retained until the local database is removed; there is no automatic retention policy. §GRUND-skopos.2 §FS-ledger

Development

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
grund check
fissile audit
git config core.hooksPath .githooks

CI pins Grund 0.13.1 and Fissile 0.9.1; these published versions are the gate. The optional pre-commit hook runs formatting, grounding, and staged file-size checks using locally installed tools. Work in branch worktrees. §FS-development.1

See architecture (§AR-ledger), the validation roadmap (§RM-validation), and the research rationale. MIT licensed; the crate is not published.