Skip to content
Signet Docs

Continuity and lineage

Session Checkpoints

Section titled “Session Checkpoints”

Session checkpoints (platform/daemon/src/session-checkpoints.ts) capture periodic snapshots of session state for continuity recovery. They store a digest of the session’s current focus, prompt count, memory queries, and recent remembers.

Checkpoints are triggered by five event types:

  • periodic — fired on a timer or prompt-count interval
  • pre_compaction — fired when the harness signals context compaction
  • session_end — fired when a session closes
  • agent — fired by agent-initiated events
  • explicit — fired by manual API calls

Each checkpoint row stores session_key, harness, project, project_normalized, trigger, digest, prompt_count, memory_queries (JSON array), and recent_remembers (JSON array). Secrets are redacted before storage using pattern-based scrubbing (Bearer tokens, API keys, base64 credential blobs, env variable values).

A buffered flush queue (queueCheckpointWrite) debounces writes at 2,500 ms intervals. If two triggers fire within the flush window for the same session, queries and remembers are merged (union with caps: 20 queries, 10 remembers) and prompt counts are summed.

Per-session caps are enforced: when checkpoint count exceeds maxCheckpointsPerSession, the oldest rows are deleted.

Digest formatters produce structured markdown for each trigger type:

  • formatPeriodicDigest — project, prompt count, duration, recent prompts, memory activity
  • formatPreCompactionDigest — same plus optional session context
  • formatSessionEndDigest — same with total prompt count

Pruning is strict: pruneCheckpoints(db, retentionDays) hard-deletes all checkpoints older than the retention window.

Configuration lives under continuity in the pipeline config:

Field Default Range Description
enabled true — Master switch
promptInterval 10 1–1000 Prompts between periodic checkpoints
timeIntervalMs 900000 60s–1h Time between periodic checkpoints (15 min)
maxCheckpointsPerSession 50 1–500 Per-session cap
retentionDays 7 1–90 Days before old checkpoints are pruned
recoveryBudgetChars 2000 200–10000 Max characters for recovery digest

Lossless Session Transcripts

Section titled “Lossless Session Transcripts”

As hooks run, Signet stores the canonical cleaned conversation transcript as JSONL at $SIGNET_WORKSPACE/memory/{harness}/transcripts/transcript.jsonl. The session_transcripts table (migration 040) remains a compatibility and indexing surface. Tool calls, tool outputs, and thinking traces are removed from these memory surfaces so retrieval and summarization stay focused on the actual conversation. Raw auditable traces may still be written to daemon logs outside the memory lineage.

The table schema (session_key TEXT PRIMARY KEY, content TEXT NOT NULL, harness TEXT, project TEXT, agent_id TEXT, created_at TEXT) is indexed on project and created_at. The summary worker writes one row per session via INSERT OR IGNORE, keyed on session_key.

The /api/memory/remember endpoint accepts an optional transcript field. When present and a sourceId (session key) is available, the transcript is written to session_transcripts in a separate write transaction. This allows connectors to push cleaned conversation text alongside memories without waiting for session-end summary processing.

At recall time, the /api/memory/recall endpoint supports expand: true. When set, session keys from the result set are batch-looked up in session_transcripts and the transcript content is joined into the response. This lets callers retrieve the full conversation context behind a recalled memory without a separate API call.

Canonical Markdown Lineage and MEMORY.md Projection

Section titled “Canonical Markdown Lineage and MEMORY.md Projection”

Rolling history now has an explicit authority split.

Canonical historical content lives as immutable markdown artifacts in $SIGNET_WORKSPACE/memory/:

  • --transcript.md
  • --summary.md
  • --compaction.md

Each session also has one mutable --manifest.md file. The manifest is the only artifact that may gain new links after session end, such as a later compaction_path.

MEMORY.md is no longer canonical history. It is a rebuildable projection over:

  • durable memory rows for the Tier 1 head
  • persisted thread heads plus temporal DAG state for Tier 2
  • canonical artifact frontmatter for the strict 30-day session ledger

The renderer is programmatic. LLM output in this lane is limited to the single memory_sentence stored in summary and compaction frontmatter, with a deterministic fallback when the quality gate fails. The final MEMORY.md projection always includes:

  • ## Global Head (Tier 1)
  • ## Thread Heads (Tier 2)
  • ## Session Ledger (Last 30 Days)
  • ## Open Threads
  • ## Durable Notes & Constraints
  • ## Temporal Index

Session-end jobs write canonical transcript artifacts immediately, then the summary worker writes the matching canonical summary artifact for normal session_end jobs. compaction-complete writes a canonical compaction artifact and backfills the session manifest. Mid-session session-checkpoint-extract jobs remain DB-native and only write checkpoint nodes into session_summaries.