Memory and Continuity

Holaboss separates memory into three different jobs:

1. resume the current session safely
2. remember durable facts, preferences, and identity
3. keep workspace instructions stable and human-readable

That split is deliberate. It prevents runtime state, long-term memory, and workspace policy from getting mixed together.

The main layers

Holaboss currently treats memory as four layers:

• session continuity lives in runtime-owned artifacts such as turn_results and compaction boundaries in state/runtime.db
• session-memory continuity projections live under memory/workspace/<workspace-id>/runtime/session-memory/
• operational projections live under memory/workspace/<workspace-id>/runtime/
• durable recalled memory lives under memory/workspace/<workspace-id>/knowledge/, memory/preference/, and memory/identity/

The canonical operator profile also lives in state/runtime.db. That profile is runtime-owned identity state, not markdown memory. The runtime also keeps pending user-memory proposals in state/runtime.db — these are input-scoped candidates such as inferred user preferences that can shape the current run ephemerally but are not promoted into durable memory until the user explicitly accepts them.

Durable vs volatile

The easiest way to think about the runtime memory model is:

Layer	Purpose	Durable?
state/runtime.db	execution truth, profile state, continuity boundaries	yes
memory/workspace/<workspace-id>/runtime/	latest-turn projections, blockers, recent-turn snapshots	no
memory/workspace/<workspace-id>/runtime/session-memory/	resume-friendly continuity snapshots	semi-volatile
memory/workspace/<workspace-id>/knowledge/	workspace facts, procedures, blockers, reference memories	yes
memory/preference/	user preferences	yes
memory/identity/	user identity memory	yes

Runtime files under runtime/ are meant for inspection and restoration. They are not treated as durable knowledge.

Source-of-truth boundary

The source-of-truth split is deliberate:

• runtime execution truth lives in state/runtime.db
• canonical operator profile data lives in state/runtime.db
• durable recalled memory lives in markdown under memory/
• standing workspace policy lives in AGENTS.md

That is what keeps continuity inspectable without turning workspace policy or durable memory into raw execution logs.

Run package and continuity artifacts

Before the harness starts, the runtime compiles the workspace, projects the capability surface, assembles prompt sections and prompt layers, computes a prompt_cache_profile, and persists a sanitized request snapshot.

The most important run and continuity artifacts are:

• turn_results
  • normalized run records with status, stop reason, token usage, prompt metadata, request fingerprint, and assistant output
• compaction boundaries
  • durable handoff artifacts that summarize a run boundary, preserve selected turn ids, and define restoration order
• request snapshots
  • sanitized request-state artifacts used for replay, debugging, and cache diagnostics
• prompt_cache_profile
  • the runtime split between cacheable and volatile prompt sections for a run
• capability manifest
  • the reduced visible and callable surface passed to the harness for that run
• memory/workspace/<workspace-id>/runtime/session-memory/
  • compact continuity snapshots used to restore the next run without replaying the full transcript

Memory lifecycle

The current flow is:

1. User input is queued, and strong-signal user-scoped proposals may be captured in state/runtime.db.
2. The runtime compiles the workspace, projects capabilities, computes the prompt package, and persists a sanitized request snapshot before the harness starts.
3. The current run may use pending proposals as ephemeral context without promoting them into durable memory yet.
4. When the run finishes, the runtime persists turn_results.
5. An immediate continuity writeback runs inline after the turn result is committed.
6. That writeback updates the compaction boundary, restoration order, and volatile runtime projections under memory/workspace/<workspace-id>/runtime/, including session-memory/.
7. The runtime then persists a queued evolve job for heavier durable-memory and skill-review work.
8. The evolve worker reloads the finished turn, recent session state, and current memory catalog state.
9. Deterministic and optional model-assisted extraction promote durable workspace facts, procedures, blockers, preference memories, and identity memories into markdown memory plus catalog rows.
10. MEMORY.md indexes are refreshed only for the durable scopes that changed.
11. Later runs restore from the latest compaction boundary first, then enrich continuity from session-memory and bounded durable recall.

Recall behavior

Runtime recall is manifest-based. The runtime scans durable markdown memory files, reads summaries and metadata, and selects a bounded set of entries to inject as context.

Important characteristics:

• runtime continuity is restored before broader memory recall
• durable memory is selected from indexed markdown, not from raw session transcripts
• stale or low-confidence memory should be penalized more than stable workspace facts
• time-sensitive reference memory should usually be reconfirmed before action
• recalled memory is context, not a rewrite of the base system prompt

Immediate continuity vs queued evolve

Holaboss splits post-run work into two phases:

1. write_turn_continuity
   • runs inline after the foreground turn_results row is committed
   • keeps next-run continuity fresh without waiting on heavier extraction work
2. queued_evolve
   • persists as a queue job in state/runtime.db
   • drains through a dedicated evolve worker
   • handles durable-memory promotion, index refresh, and background skill review

The immediate continuity phase keeps the next run cheap to restore. The queued evolve phase handles slower work such as:

• deterministic durable candidate extraction
• optional model-assisted durable extraction when background tasks are configured
• durable markdown upserts and MEMORY.md refresh
• reusable workspace skill review and candidate drafting

Skill candidate lifecycle

Reusable procedural patterns do not become live skills automatically. The current lifecycle is:

1. queued evolve reviews a cadence turn
2. if it finds a reusable pattern, it writes a draft under memory/workspace/<workspace-id>/evolve/skills/<candidate-id>/SKILL.md
3. the runtime stores candidate metadata in state/runtime.db
4. candidate skills that merit attention are raised through proposal surfaces rather than silently activated
5. an accepted proposal opens a tightly scoped review session
6. after successful review, the candidate can be promoted into the live workspace skills/ namespace

Durable memory types

The durable memory catalog currently supports these memory classes:

• preference
  • stable user preferences such as response style
• identity
  • durable identity facts beyond the canonical runtime profile
• fact
  • workspace command facts or business facts that should survive later runs
• procedure
  • reusable operational steps such as release, onboarding, follow-up, or handoff workflows
• blocker
  • recurring permission or execution blockers that appear across turns
• reference
  • durable references that should usually be reconfirmed before use

Current writeback is intentionally conservative. The runtime should only promote facts and procedures that are explicit enough to survive beyond a single turn, and it should keep transient runtime state out of durable knowledge.

Recall and governance

Durable recall is governed separately from storage:

• every durable memory entry carries a scope, type, verification policy, and staleness policy
• every durable memory entry also carries provenance metadata such as source type, observation time, verification time, and confidence
• recall should prefer user preferences first, then query-matched workspace procedures, facts, blockers, and references
• stale references should be penalized more aggressively than stable or workspace-sensitive memories
• recalled durable memory is injected as context, not merged into the base system prompt

Recall selection is staged at query time. The runtime reads durable-memory indexes, and when recall embeddings are available it can first narrow candidate paths through a derived vector index. It then reads only those candidate leaf files and finalizes a small recalled subset for prompt injection. Markdown leaves remain the canonical content source, while vector rows stay derived recall acceleration only.

What lives where

Use these rules of thumb when reasoning about the system:

• AGENTS.md
  • human-authored workspace policy and operating instructions
• state/runtime.db
  • execution truth, session continuity, canonical runtime profile, memory catalog metadata
• memory/workspace/<workspace-id>/runtime/
  • volatile runtime projections for inspection and debugging
• memory/workspace/<workspace-id>/runtime/session-memory/
  • session-scoped continuity snapshots used during resume restoration
• memory/workspace/<workspace-id>/knowledge/
  • durable workspace memory that may be recalled in later runs
• memory/preference/
  • durable user preference memory
• memory/identity/
  • durable user identity facts beyond the canonical runtime profile

If a piece of information is only needed to resume the latest session, it belongs in runtime continuity. If it is the canonical current-user identity used by the runtime, it belongs in the runtime profile. If it should be recalled later without replaying the full session, it belongs in durable memory. If it is a standing workspace rule, it belongs in AGENTS.md.

Namespace boundaries

Memory paths are memory-root-relative. The runtime rejects:

• absolute paths
• .. traversal
• paths that escape the memory root

The current namespace model allows:

• root index: MEMORY.md
• workspace scope: workspace/<workspace-id>/*
• user/global scopes such as preference/* and identity/*

Cross-workspace access is blocked. A workspace can only read or write its own scoped memory.

Why this matters

This model gives the runtime three distinct guarantees:

• it can resume a run without replaying everything
• it can remember durable facts, preferences, and identity without treating them as session logs
• it can keep workspace instructions stable and auditable

That is the core of Holaboss continuity.