Osprey persists conversations, tool records, usage, forks, child outcomes, and selected runtime state. The same state supports the terminal user interface (TUI) and osprey agent.

Osprey home directory

Osprey resolves its state directory in this order:

A non-empty OSPREY_HOME environment variable wins.
Osprey uses ~/.osprey when the operating system reports a home directory.
Osprey uses ./.osprey when neither source exists.

An empty OSPREY_HOME value is treated as unset. Set OSPREY_HOME when a test, container, or separate profile needs isolated state.

Project configuration remains separate from the state directory. Osprey searches upward for the nearest .osprey/config.toml within the workspace boundary. Malformed project configuration stops launch. Malformed global configuration produces a warning and uses defaults.

Database backends

The default database is SQLite at $OSPREY_HOME/sessions.db. Set database_url in global configuration to use another SQLite file or PostgreSQL. Project configuration cannot replace the database connection.

SQLite startup creates the parent directory and database file when needed. The connection enables foreign keys and write-ahead logging (WAL). SQLite sets a five-second busy timeout, NORMAL synchronization, and a 500-page automatic checkpoint. Bootstrap retries recognized concurrent-open and migration races.

Osprey runs the schema migrations before it creates a session. A migration or connection failure stops launch. Normal teardown checkpoints and truncates the SQLite WAL file. PostgreSQL connections do not require the local WAL checkpoint.

osprey setup tests the selected database connection. A failed setup test does not prevent the wizard from saving the configuration. The wizard reports the failure before it asks to save.

Session records

Each session records its working directory, provider, model, timestamps, kind, and optional name. Forked sessions also record parent and root identifiers. Subagents use child session records and persist their terminal outcomes.

The ordered entry stream can contain these records:

User, assistant, and tool-result messages.
Tool calls and their completion records.
Provider, model, persona, and reasoning changes.
Usage snapshots and completion checkpoints.
Compaction envelopes and fork metadata.
Subagent outcomes.

Mixture of Agents traces use a separate database table. They do not appear in the ordered session-entry stream.

The TUI creates a fresh user session at initial launch. /new creates another fresh session. Switching sessions restores the stored provider, model, persona, transcript, usage, and completion state.

The headless command creates a fresh session unless a resume or fork option is present. --resume SESSION_ID appends to the selected session. --fork-from SESSION_ID copies the source through its latest sequence into a new child. Both options require a persistent database. Osprey rejects both options with an in-memory store.

Resume and fork restore the persisted provider and model. Launch fails when the stored provider is unavailable or lacks current credentials.

Session commands

The command-line interface (CLI) scopes session listing and resolution to the current directory.

list shows identifier, label, state, entry count, and update age. tree shows parent and child relationships. fork accepts a full identifier, a unique prefix, or a branch label. The sequence must identify a valid cut without an open tool call. The source session remains unchanged.

switch marks the selected session active. In the TUI, switching hydrates the selected transcript. Switching also replays that transcript.

delete performs a soft deletion. Osprey refuses to delete the active session in the current window. The confirmation requires the complete Universally Unique Identifier (UUID), even when lookup used a label or prefix. A matching confirmation exits with status 0. A canceled confirmation exits with status 130. Every other unsuccessful session operation exits with status 1.

The next commands can create, activate, or soft-delete session records.

osprey session list
osprey session tree
osprey session fork SESSION --at SEQUENCE
osprey session switch SESSION
osprey session delete SESSION

Journaling and durability limits

One asynchronous journal writer preserves entry order for each active session. The agent allocates sequence numbers before it queues entries. A turn-complete barrier waits for the previous turn's queued writes. Session activation drains the old queue before changing journal ownership. Normal shutdown drains the remaining queue.

The barriers provide ordered persistence during normal operation. The barriers do not make every current-turn event synchronous. A process crash can lose entries that remain in the queue.

The first journal write failure marks the writer failed. The journal then skips every later queued entry. The live agent can continue after a journal storage failure. Inspect logs when a resumed transcript lacks later events.

Approval persistence uses a separate file and lock. The approval file uses an in-place rewrite instead of an atomic rename. A crash during the rewrite can leave an empty or malformed approval file. The next launch treats either state as an empty approval store.

Conversation compaction

Conversation compaction summarizes an old message prefix and keeps a recent tail. Osprey stores the replacement and its provenance as one compaction checkpoint. Older active entries become compacted records instead of being deleted. Resume loads the replacement prefix and the active tail.

Automatic compaction starts at 85 percent of the known usable model window. Automatic compaction is disabled when the model window is unknown. The proposed cut must remove at least four messages. Osprey keeps between 2,000 and 8,000 estimated tokens in the tail.

The summarizer receives at most 262,144 serialized bytes. The summarizer timeout is 120 seconds. Osprey keeps the original live context when summarization fails. An automatic repeat is skipped after a prior compaction saves less than ten percent.

Automatic and manual compaction skip while any child agent remains active. Provider-overflow recovery waits at most three seconds for active children. The summary identifies children that remain pending after the three-second wait. Compaction does not start with less than 60 seconds of session budget.

Use /compact to request manual compaction in the TUI. Manual compaction bypasses the 85-percent pressure rule and the anti-thrash rule. Manual compaction still applies the child, budget, and viable-cut gates.

Tool-result compression and retrieval

Tool-result compression is separate from conversation compaction. The [tool_results].compress_context setting and --compress-context=true option control tool-result compression. The default is false.

When enabled, Osprey examines large non-streaming outputs before adding them to model context. The compressor handles structured JavaScript Object Notation (JSON), search lines, code, and directory listings. Plain prose is not compressed. bash and retrieve output never use semantic compression.

Before replacing output, Osprey writes the byte-exact original to a sidecar file. The visible result contains a digest and a retrieve(handle=CALL_ID) marker. The conditional retrieve tool returns the original bytes.

A failed sidecar write disables semantic compression for the affected result. Osprey then uses normal head-and-tail truncation when a size limit applies. The retrieve tool is absent when semantic compression is disabled.

The default byte cap is 32,768 bytes. The default preserved head and tail are 12,288 bytes each. The default line trigger is disabled. Setting both byte and line limits to zero disables result capping.

Files and directories

The following table lists user-visible state and generated artifacts.

Path or output	Purpose and retention
`$OSPREY_HOME/config.toml`	Global configuration. Osprey preserves comments and unknown keys during setup updates.
`$OSPREY_HOME/sessions.db`	Default SQLite database. Sessions have no automatic deletion deadline.
`$OSPREY_HOME/logs/`	TUI log directory. Osprey does not apply a retention sweep.
`$OSPREY_HOME/raw/`	Default TUI sidecars for full tool output. Startup removes files older than seven days by default.
`$OSPREY_HOME/approvals.toml`	Saved tool approvals. A missing or malformed file becomes an empty store.
`$OSPREY_HOME/trust.toml`	Pinned trust hashes for project extensions. Malformed content is an error.
`$OSPREY_HOME/workflow_trust.toml`	Saved workflow grants keyed by scope, name, and script digest.
`$OSPREY_HOME/workflows/runs/RUN_ID/`	Workflow `ledger.jsonl` and spilled output. The default retention is unlimited.
`$OSPREY_HOME/memory/MEMORY.md`	Built-in project memory entries. Mutations use a lock and atomic replacement.
`$OSPREY_HOME/memory/USER.md`	Built-in user memory entries. Mutations use a lock and atomic replacement.
`$OSPREY_HOME/cache/`	Cached model catalogs. Later refresh effects can replace cached data.
`$OSPREY_HOME/command_usage.toml`	TUI slash-command usage data for completion ranking.
`$OSPREY_HOME/processes/`	Durable records for preserved headless process groups.
`$OSPREY_HOME/crash/`	TUI panic reports. Osprey uses the system temporary directory when creation fails.
`--atif-output PATH`	Agent Trajectory Interchange Format (ATIF) version 1.7 trajectory. The final write uses an atomic replacement.
`osprey-SESSION_ID-TIMESTAMP.md`	Default TUI transcript export name. The export dialog selects the final path.
Standard output	Human output on a terminal. Headless output becomes JSON Lines when redirected or requested with `--events-jsonl`.

The ATIF file contains a system-prompt digest by default. --atif-system-prompt-plaintext adds the rendered system prompt. An ATIF flush failure produces a warning and does not change a successful agent outcome.

For headless runs, --tool-result-raw-dir PATH selects the sidecar directory. Without --tool-result-raw-dir, --atif-output PATH selects a sibling raw/ directory. Without either option, capping remains active but full-output spilling is disabled.

The tool-result retention default is seven days when a sidecar directory exists. Osprey sweeps the selected sidecar directory during launch. Failed spill and sweep operations produce warnings without stopping the agent.

A positive [workflows].run_retention_days value enables workflow-run deletion. The default is absent and retains workflow runs without a deadline. A value of 0 also disables deletion. Deleting old workflow directories can orphan spill paths stored in long-lived sessions. The workflow ledger is a best-effort diagnostic artifact. Workflow resume uses the active process registry and does not recover a run after process restart.

The TUI archives idle session trees after 30 days by default. The TUI session-tree view triggers the archive pass. Archiving hides a tree from the active view but does not delete its database records.

Malformed built-in memory files receive a timestamped .bak copy. Osprey then refuses the requested memory mutation. Repair the original file before another mutation.

Manage tool subprocesses

In an unsandboxed tool catalog, bash can start a command with background = true. The call returns immediately with a process identifier and ignores its timeout value. Background mode cannot be combined with validation = true.

For foreground tests, builds, linters, and other checks, validation = true enables shell errexit and pipefail behavior. When a foreground command blocks for input in the TUI, Osprey opens an input pane automatically.

The process tool manages commands started with bash(background = true). Its list action lists them. Its poll action returns output since the prior poll. Its write action sends input, with newline = true by default. Its kill action terminates the process group. The poll, write, and kill actions require the background process identifier.

The sandbox sidecar omits the process tool.

Preserved background processes

The headless parent dispatcher preserves background bash process groups after every outcome except budget expiration. TUI processes, subagent processes, and auxiliary driver processes terminate during teardown. Budget expiration also terminates parent background groups.

Each preserved record contains a durable identifier, process identifier, group identifier, birth fingerprint, command, directory, owner, and start time. Registration writes private files through an atomic publish step.

list observes registered groups. It removes records for groups that already exited. terminate handles one record. clean takes one registry snapshot and handles every record in that snapshot.

Before signaling, Osprey verifies the record identifier, process group, and birth fingerprint. An identity mismatch or unverifiable record remains untouched. The command reports identity_mismatch or unverifiable instead of signaling an unrelated process.

Termination sends SIGTERM to the verified process group first. After two seconds, Osprey sends SIGKILL if the group still runs. A successful termination removes the durable record. An already exited group also counts as success.

clean continues after corrupt, unverifiable, or failed records. The command exits nonzero when any snapshot entry remains unresolved. Use --json for stable machine-readable status names.

The next commands can signal processes and remove durable process records.

osprey process list [--json]
osprey process terminate PROCESS_ID [--json]
osprey process clean [--json]

Back to Osprey