How AgentSight background monitoring samples agent sessions

The short answer

AgentSight v1.0.31 samples up to 25 matched live agent sessions on a two-second loop. Every sampled session gets a monitor_windows row with process count, CPU delta, resident memory, read/write byte deltas, and counts of visible file and network targets. Detailed process and target rows are not written on every loop: the implementation stores them only when a sample crosses a 30-second boundary.

The result is a local SQLite database under ~/.agentsight/monitor. The product itself describes these DBs as sampled, windowed evidence rather than a complete trace. If you need the exact sequence of process, file, or TLS events for one bounded run, use the durable record path instead of inferring missing events from a background monitor window.

One monitor loop has two resolutions

Resolution	Persisted data	Useful question	Do not infer
Every ~2 seconds	Session identity, process count, CPU ms, RSS bytes, read/write byte deltas, file-target count, network-target count.	When was this session active, resource-heavy, or associated with many visible targets?	The exact process/file/network event sequence inside the window.
At ~30-second boundaries	Bounded process rows plus bounded file and network target rows for that window.	Which concrete processes or targets are representative near this part of the run?	That omitted rows never existed; detail is intentionally sampled and bounded.

The 30-second gate is implemented by comparing the integer 30-second bucket containing the start and end of the current two-second window. It is therefore a boundary sample, not a second independent timer that records an exhaustive 30 seconds of events.

The aggregate row is richer than a process count

For each matched session, the monitor walks the current process family. It computes CPU time as a delta from the previous process snapshot, reads current RSS, and derives read/write byte deltas from per-process I/O counters. The row also carries the root PID together with its process start-time ticks. That extra start-time identity matters because a PID can be reused after a process exits.

The tracked_sessions table keeps first/last-seen timestamps, agent type, match evidence and confidence, optional native-session path, command, working directory, and a running status. Its key combines session ID, root PID, and root process start time rather than assuming the numeric PID is globally stable.

File targets are open-descriptor observations, not file-operation logs

The monitor's file view is built from /proc/<pid>/fd. For every process in the matched family, AgentSight scans current descriptor targets, keeps absolute paths, and excludes the common/dev/null and /dev/zerosinks. It re-checks the process start time around the scan so PID reuse does not silently attach another process's descriptors to the old session.

A path appearing in a monitor DB means it was visible as an open descriptor at a sampling point. A path missing from the DB does not prove it was never opened, read, written, renamed, or deleted between samples. For a review that depends on exact low-level file events, use a recording source designed to capture them.

Network targets are sampled IP endpoints, not HTTP requests

Socket descriptors are resolved through Linux /proc TCP tables. The implementation maps socket inodes to IPv4 or IPv6 endpoints and stores an address plus port. It does not turn that row into a DNS name, HTTP route, request body, or security verdict. A target such as 203.0.113.10:443 is an endpoint observation at that sampling boundary.

This is intentionally different from AgentSight's TLS/model-call capture. Background network samples are useful for “which destinations were visible around the resource spike?” They are not a replacement for the content and protocol evidence needed to explain a specific API call.

Detailed rows are capped at the edges

A session can have many processes, paths, or sockets. To keep a long-running monitor database bounded, v1.0.31 uses a detail-edge limit of five. When there are more than ten candidate process rows, it stores up to five from the high end of a score ordered by CPU, then RSS, then I/O, and fills the remainder from the low end. File and network target details use the same five-plus-five shape, ranked primarily by observed count.

The aggregate window still stores total process count and the number of distinct visible file/network targets. The detailed tables are therefore examples from the edges of the sampled set, not an exhaustive expansion of those totals. Treating the detail table row count as the real process or target count would be a measurement error.

The “weekly DB” name has a restart boundary in v1.0.31

AgentSight names the default database by the local ISO week, for example~/.agentsight/monitor/monitor-2026-W25.db. One implementation detail is easy to miss: the database path is chosen when monitor starts and the store is opened once before the sampling loop. The loop does not reopen the database when the calendar crosses into another ISO week.

So in v1.0.31, a monitor process that runs continuously across a week boundary can continue writing to the file named for its start week until it restarts. The installation guide recommends restarting the user service or scheduled task after replacing the binary; a restart also causes the next monitor process to select the then-current week filename. Do not assume filename alone proves every row belongs to that ISO week; use the stored window timestamps when analyzing boundaries.

`monitor` and `bind` solve different background jobs

The installation guide separates the two explicitly. monitor samples active sessions and writes local weekly databases. bind serves the authenticated Node API and maintains the optional outbound Controller relay. Running the browser-facing Node does not mean the monitor is persisting a background history, and running the monitor does not expose a new browser API port.

On Linux, agentsight monitor install-service installs a per-user systemd service withRestart=on-failure. The built-in service installer is Linux-specific; the current installation guide uses a per-user scheduled task for Windows. Both are operational wrappers around the sameagentsight monitor subcommand.

The database is local, but the rows can still be sensitive

The monitor schema can persist commands, working directories, native-session paths, file paths, and network endpoints. The broader AgentSight README warns that saved logs and databases can contain sensitive prompts, responses, paths, headers, and network targets depending on the capture source. The installation guide also notes that removing startup units does not remove existing monitor databases.

Operationally, treat ~/.agentsight/monitoras retained evidence: set host-level permissions and retention according to the machine's data policy, and delete old databases separately only when their evidence is no longer needed. Do not commit them into a source repository as a convenient debugging artifact.

Use monitor evidence for trends; switch sources for exact causality

Question	Best starting evidence
Which agent sessions were active during a CPU/RSS spike?	Monitor windows.
Which file or endpoint was visible near a sampled spike?	Monitor detail rows, with the sampling caveat preserved.
Did a short-lived file open occur between samples?	A full system recording, not absence from the monitor DB.
Which exact plaintext model request produced an action?	Recorded model/TLS evidence plus correlated system activity.
What did the agent itself persist about models, tools, or tokens?	Native agent-session evidence or the appropriate report path.

How to verify the behavior yourself

The reproducible source for this page is the v1.0.31 implementation. Start with cmd_monitor.rs: inspect the two-second loop, 30-second detail gate, process and descriptor scans, edge-bounding functions, weekly path function, and SQLite schema. Then read the installation guide for the service lifecycle and the monitor/bind boundary.

If you are using a monitor DB for an investigation, keep the raw window timestamps and source version with your analysis. Those two fields are more reliable evidence than assuming the filename or a missing detail row means more than the implementation actually guarantees.