Checkpointing in MindStone

Subtitle: A technical whitepaper on governed synthesis, durable memory promotion, and verification across coding-agent substrates

Status: Technical whitepaper draft
Date: 2026-06-22
Author: Clint Bodungen
Project context: MindStone Agent, MindStone-Agent, MS4CC, MS4PI, MS4Codex/MS4CDX, MS4Gemini/MS4GMNI
Companion to: Layered Continuity Architecture for Persistent LLM Agents

Executive summary

Persistent agents do not become continuous merely because their transcripts are saved. A transcript preserves what happened, but it does not decide what should become durable memory, what should be treated as a temporary detail, what should change future behavior, or whether the recall substrate can actually find the new material later.

MindStone uses checkpointing to solve that problem.

A checkpoint is a governed synthesis and verification cycle. It is the moment where recent operational experience is reviewed, important facts and lessons are promoted into durable continuity artifacts, the chronological LOG is updated, memory indexes are maintained, transcripts are archived, embeddings are backfilled, and recall health is verified.

The core principle:

A checkpoint is not a save point.
A checkpoint is governed continuity promotion plus verification.

In MindStone for Claude Code (MS4CC), checkpointing is implemented as the /checkpoint command and is described as the dream-cycle point where session experience becomes persistent memory. In MindStone for Pi (MS4PI), the equivalent command is /ms-checkpoint, adapted to Pi’s extension model and tool surface. The same protocol should carry forward into MindStone for Codex (MS4Codex/MS4CDX), MindStone for Gemini (MS4Gemini/MS4GMNI), and other closed or semi-closed coding-agent substrates.

Checkpointing is especially important in substrates where MindStone does not own the live prompt assembly path. In MindStone-Agent proper, sliding-window context management can preserve the append-only transcript while pruning the live prompt. In Claude Code, Pi, Codex, Gemini CLI, and similar harnesses, the agent may have hooks, extensions, slash commands, or event surfaces, but it often cannot fully control compaction, prompt pruning, or the model’s working context. Checkpointing compensates by ensuring the continuity substrate remains rich and verifiable even when the active context window is outside MindStone’s direct control.

A complete checkpoint should:

synthesize what happened;
identify decisions, lessons, corrections, and open drift;
search existing memory before creating new memory;
update existing memories where suitable;
create new memory only when warranted;
update the memory index;
append the LOG;
archive the live transcript;
backfill and embed memory/transcript chunks;
verify recall/index status;
record what was verified and what remains incomplete.

The short version:

Summary says what happened.
Handoff prepares the next state.
Checkpoint decides what becomes durable and proves it is recallable.

1. Problem statement

LLM agent sessions produce a large amount of useful operational experience:

decisions made in the middle of implementation;
user corrections;
project facts;
test results;
failed hypotheses;
root causes;
file paths and command sequences;
safety constraints;
role-specific standards;
product positioning decisions;
memory system design changes;
unresolved drift;
near misses and prevented mistakes.

Some of that experience should shape future behavior. Some of it should remain only in the transcript. Some of it should become structured memory. Some should be logged chronologically. Some should be indexed for recall. Some should be ignored.

If the system simply saves transcripts, future agents may still fail to learn. The relevant fact may exist somewhere in a JSONL file but never return when needed.

If the system simply summarizes, it may compress away the texture that made the lesson important.

If the system simply embeds every transcript chunk, recall may find semantically similar material but miss the durable lesson, source authority, approval status, or verification state.

If the system writes memory automatically without governance, it can turn transient conversation, wrong assumptions, or sensitive details into persistent belief.

Checkpointing exists because persistent agents need a disciplined answer to this question:

What from this session should become part of future continuity, and how do we know it actually landed?

2. What a checkpoint is

A checkpoint is a governed synthesis and verification cycle.

It is usually run at a natural boundary:

after completing meaningful work;
before compaction;
at session end;
after a user correction;
after a production fix;
after a design decision;
after a mistake or near miss;
before a role transfer;
before a context reset.

A checkpoint produces or updates several continuity artifacts:

LOG.md
structured memory files
MEMORY.md index pointers
transcript archives
vector/index chunks
recall status
handoff context when needed

A checkpoint is not complete merely because a LOG entry exists. LOG is the chronological ledger, but durable memory belongs in memory files, source history belongs in transcripts, and recall depends on backfill/index verification.

In MindStone terms:

LOG records the checkpoint.
Memory carries durable lessons.
Transcript preserves source history.
Indexing makes sources recallable.
Verification proves the substrate caught up.

3. What a checkpoint is not

3.1 Not a generic summary

A summary compresses prior context.

A checkpoint decides what should become durable and verifies that the continuity substrate has been updated.

A summary might say:

Fixed the docs rendering issue.

A checkpoint should preserve:

what the root cause was;
what files changed;
what was tested locally;
what was verified live;
what memory lesson should prevent recurrence;
what remains unresolved;
whether the transcript and memory files were indexed.

3.2 Not a handoff

A handoff prepares the next agent state to resume work.

A checkpoint updates durable continuity.

They often happen together near compaction, but they are different artifacts.

A handoff asks:

What does the next agent state need to know immediately?

A checkpoint asks:

What should future agent states remember durably, and has the substrate verified it?

3.3 Not compaction

Compaction reduces live context size.

Checkpointing preserves and promotes continuity before, during, or after compaction boundaries.

A compaction summary can be lossy. A checkpoint should remain source-aware and auditable.

3.4 Not Auto Recall

Auto Recall retrieves relevant memory before inference.

Checkpointing writes, updates, indexes, and verifies the material that Auto Recall may retrieve later.

Recall consumes the continuity substrate. Checkpointing maintains it.

3.5 Not vectorization alone

Embedding transcript chunks makes them searchable. It does not decide which lessons deserve structured memory, which memory should be updated, which source is authoritative, or whether a user approved the durable wording.

Vectors are a retrieval layer. Checkpointing is a governance layer.

3.6 Not a save button

The term “checkpoint” can sound like saving game state. That is not the MindStone meaning.

A save point preserves state. A MindStone checkpoint reviews experience, promotes meaning, writes durable artifacts, and verifies the substrate.

4. Why checkpointing matters in Layered Continuity Architecture

Layered Continuity Architecture separates memory into cooperating layers:

identity
user context
append-only transcript
structured memory
journals
LOG
recall index
live context management
handoff
checkpoint/consolidation

No single layer has to pretend to be memory by itself.

Checkpointing is the layer that coordinates promotion between layers.

Without checkpointing:

transcript exists but may not become usable memory;
memory files may become stale or duplicated;
LOG may miss decisions;
recall may not index new artifacts;
handoff may preserve only immediate task state;
future agents may repeat corrected mistakes;
verification claims may not be recorded;
compaction can erase the live texture before durable synthesis occurs.

With checkpointing:

important session experience is reviewed while context is still rich;
durable memories are proposed or updated deliberately;
memory index pointers keep the corpus navigable;
LOG provides chronological audit;
transcript archive preserves source history;
vector/index backfill makes new context recallable;
recall status proves whether the substrate is healthy;
open drift is visible instead of silently forgotten.

The checkpoint therefore acts as a continuity promotion gate.

Experience enters through transcript.
Checkpoint promotes selected experience into durable memory.
Recall brings that memory back later.

5. The checkpoint artifact bundle

A MindStone checkpoint is a bundle, not a single file.

The bundle usually includes:

a LOG entry;
memory file creations or updates, if warranted;
MEMORY.md index entries or pointer edits;
prevented-confirmation accounting;
drift findings;
archive/backfill/embed verification;
handoff updates when a boundary is near.

The order matters.

A typical checkpoint flow:

review session
→ search existing memory
→ decide update vs new memory
→ draft checkpoint bundle
→ request approval if required
→ write memory/index updates
→ append LOG
→ archive transcript
→ backfill/embed/index
→ verify recall status
→ record completion evidence

If memory is warranted but only LOG is appended, the checkpoint is incomplete.

If LOG and memory are written but the transcript/index is not backfilled, the checkpoint is incomplete.

If archive/backfill fails and the failure is not surfaced, the checkpoint is incomplete.

The operational rule:

A checkpoint is complete only when meaning and mechanics both land.

6. LOG.md: the chronological ledger

LOG.md is the chronological record of checkpoints, role spans, session outcomes, drift, and verification.

A typical MS4CC/MS4PI checkpoint LOG entry includes:

## YYYY-MM-DD — short title

**Project(s):** [list]
**Scope:** one-line summary

### What happened
- ...

### Decisions made
- ...

### Memories cited
- filename.md — why it was useful

### Prevented confirmations
- filename.md — confirmed by Clint

### New memories proposed
- ...

### Drift flagged
- ...

### Lint
- ...

LOG should be concise enough to scan, but specific enough to audit.

It should record:

what changed;
what was decided;
what was verified;
what was not verified;
which memories were cited;
which memories prevented mistakes;
which new memories were written or intentionally skipped;
whether archive/backfill/index verification succeeded;
what drift remains.

LOG is not a replacement for structured memory. It is the operational ledger that records the checkpoint event.

7. Structured memory promotion

Structured memories carry durable, reusable knowledge.

A checkpoint should ask:

Did this session produce something future agent states should remember outside the transcript?

Examples of warranted memory:

a recurring user preference;
a project design decision;
a technical lesson from a production bug;
a corrected false assumption;
a public positioning rule;
a safety boundary;
a substrate-specific limitation;
a stable implementation fact;
a cross-session backlog item.

Examples that may not warrant memory:

one-off command output;
temporary task chatter;
a fact already captured in an existing memory;
unverified speculation;
short-lived implementation detail;
sensitive material not appropriate for the memory layer.

The checkpoint must search existing memory before creating new memory.

If a similar memory exists, update it. Do not create duplicate memory just because the current wording is fresh.

A memory should have clear scope. A good memory file can answer:

What is this memory for?
When should future recall use it?
What mistake or omission does it prevent?
What project or design area does it constrain?

8. MEMORY.md: the navigable index

MEMORY.md is not just a directory listing. It is a curated map of the memory corpus.

When a checkpoint creates a new memory file, it should also add a pointer to MEMORY.md.

The pointer should explain what the memory covers, not merely repeat the filename.

Example:

- `lesson_website_starlight_tailwind_production_css.md` — Production Starlight docs rendering can break if the docs shell imports the marketing Tailwind/global stylesheet; local dev may mask the issue due to different CSS order.

Without an index pointer, future agents may have a harder time knowing that the memory exists or why it matters.

A checkpoint that writes memory files but does not update the memory index is incomplete.

9. Prevented confirmations

MindStone memory is not only a store of facts. It is also a record of what has mattered.

MS4CC introduced an “Option D” prevented-confirmation flow: when memories are cited during a session, the checkpoint can ask which of those memories actually prevented a mistake. Confirmed memories increment prevented.

This matters because future recall ranking can use prior usefulness as a signal.

A memory that prevented a real mistake should carry more weight than a memory that merely matched the current text.

The goal is not ritual. The goal is experience-weighted memory.

Good prevented-confirmation candidates:

a lesson that stopped the agent from overclaiming;
a user preference that changed the answer;
a project memory that prevented duplicate work;
a security boundary that prevented disclosure;
a technical lesson that avoided repeating a known bug.

Poor candidates:

a memory that was merely listed;
a memory that had no effect on behavior;
a memory that was vaguely related but not actually useful.

The checkpoint should be honest. If no memory clearly prevented a mistake, say so.

10. Drift detection

Checkpointing is also where drift becomes visible.

MS4CC and MS4PI checkpoint lint commonly checks for:

role-shaped work without role adoption;
non-trivial decisions without canonical attribution;
memory contradictions;
shipped work without updating task status or equivalent artifacts;
durable facts left only in transcript;
memories warranted but not written;
unverified claims;
unresolved failures;
local-only changes not committed or not intended to be committed.

Drift is not automatically failure. It is unintegrated state.

The checkpoint should name it so future work can handle it deliberately.

Example drift entry:

MindStone-Agent remains MVP-shaped but not MVP-proven until live Pi-session prompt/stream and compaction validation pass.

That kind of drift prevents future agents from treating scaffolded implementation as validated product state.

11. Archive, backfill, embed, verify

A checkpoint has a mechanical half.

The mechanical half preserves source history and makes it recallable.

Typical operations:

archive live transcript
index memory files
index transcript chunks
embed changed/new chunks
write or update vector DB
run recall status
record chunk counts and errors

This is not decorative. A memory file that is written but not indexed may not be returned by Auto Recall. A transcript that is not archived may be unavailable after a substrate boundary. A vector DB that failed silently can make continuity appear healthy while recall is actually degraded.

A checkpoint should record verification evidence.

Example:

mode: semantic
chunks_total: 1985
chunks_memory: 108
chunks_transcript: 1877
error: null

The exact fields vary by implementation, but the principle is stable:

Do not claim checkpoint completion unless archive/backfill/index status was checked.

12. MS4CC checkpoint protocol

MS4CC is the reference coding-agent substrate implementation for this checkpoint pattern.

The command is:

/checkpoint

It is described as:

Dream-cycle checkpoint — synthesize this session, update LOG.md, increment memory weights, flag drift.

Its protocol includes:

synthesize the session into a LOG entry;
identify cited memories and ask which prevented mistakes when useful;
search existing memory before proposing new memory;
draft new memory files or updates;
flag drift;
append LOG after approval;
explicitly run archive/vectorize.

The crucial MS4CC design correction is that per-turn hooks should not do expensive embedding.

Current MS4CC behavior separates cheap and expensive work:

Stop hook: archive live transcript and update hit counters.
/checkpoint step 7: run checkpoint mode to embed transcript and reindex changed memory.
PreCompact: archive transcript and refresh recent tail immediately before compaction.

MS4CC’s session_end.py uses CAIRN_CHECKPOINT_MODE=1 as the explicit checkpoint embedding path. In that mode, it performs transcript vectorization and memory reindex. The per-turn Stop hook archives only because re-embedding the transcript every turn ran the local embedder hot.

The practical command is:

CAIRN_CHECKPOINT_MODE=1 orchestrator/.venv/bin/python orchestrator/hooks/session_end.py < /dev/null

The < /dev/null fallback matters because the script normally receives hook JSON on stdin. When invoked manually, it can locate the most recent session transcript by mtime if stdin is empty.

A successful checkpoint-mode run should print a clear summary. No output or a degraded vector stack must not be treated as success.

12.1 MS4CC and compaction

MS4CC cannot rely on the agent controlling /compact exactly when needed. Claude Code compaction may be human-initiated or harness-initiated.

Therefore MS4CC uses a belt-and-suspenders continuity design:

warning threshold
→ rich handoff/checkpoint judgment
→ PreCompact archive + RECENT TAIL refresh
→ compaction
→ post-compact handoff replay
→ deferred embedding/backfill

The checkpoint is the governed synthesis layer. PreCompact is the last-moment mechanical freshness layer. Handoff is the resumption layer.

They cooperate, but they are not the same thing.

13. MS4PI checkpoint protocol

MS4PI adapts the MS4CC checkpoint protocol to Pi’s extension model.

The command is:

/ms-checkpoint

MS4PI private state lives under:

~/.pi/agent/mindstone/orchestrator/

with the same core artifacts:

IDENTITY.md
USER.md
LOG.md
memory/MEMORY.md
memory/*.md
transcripts/.handoff.md
vectors.db

MS4PI preserves the MS4CC checkpoint structure:

draft LOG entry;
identify durable new memories or updates;
search existing memory first to avoid duplicates;
draft exact memory files or edits;
draft exact MEMORY.md pointer updates;
ask Clint for approval of the checkpoint bundle;
treat approval as covering LOG plus warranted memory/index writes unless explicitly narrowed;
write memory/index updates first;
append LOG;
run archive/backfill/status verification.

The ordering is intentional.

A LOG-only checkpoint is insufficient when durable memory is warranted.

MS4PI’s extension registers approval-gated tools for:

mindstone_memory_write
mindstone_log_append
mindstone_handoff_write

The tool instructions enforce the intended separation between draft and approved write.

13.1 MS4PI mechanical path

MS4PI uses Pi events rather than Claude Code hooks.

Relevant mappings:

MS4CC	MS4PI
`SessionStart`	`session_start` plus `before_agent_start` context injection
`UserPromptSubmit`	`before_agent_start` prompt-time recall
Stop/session-end archive	explicit `/ms-recall-backfill` or `/ms-end-session`, plus event-based helpers
`PreCompact`	`session_before_compact`
post-compact replay	`session_compact` flag plus next `before_agent_start`

The compaction watchdog checks context usage during turn_end and, at the configured warning threshold, prompts Slate to draft both checkpoint and handoff before the compaction danger zone.

Default policy:

checkpointWarningPercent: 85
compactTargetPercent: 92
keepRecentTokens: 20000
emergencyAutoHandoff: false

MS4PI deliberately does not write rich checkpoint or handoff content without approval by default.

Mechanical operations such as transcript archive, recent-tail refresh, and recall backfill can run at lifecycle boundaries, but meaning-making remains governed.

13.2 Current validation stance

MS4PI has implemented the checkpoint/handoff/recall-backfill shape, and Slate has used the checkpoint workflow in real sessions.

However, public claims should remain precise:

Do not claim full MS4CC parity until the target Pi version’s live checkpoint, compaction, replay, and recall paths have been tested end to end.

This is not a weakness of the checkpoint concept. It is claim discipline around substrate-specific lifecycle events.

14. Approval semantics

Checkpointing creates durable artifacts. Durable artifacts require governance.

In MS4CC/MS4PI practice, the agent should draft the checkpoint bundle first and ask for approval before writing.

The bundle should include:

exact LOG entry;
exact new memory file bodies or memory edits;
exact MEMORY.md index entries;
handoff body if part of the same boundary flow;
any verification steps that will run after writes.

Once the checkpoint bundle is approved, a second approval round should not be required for each memory write unless the user explicitly narrowed approval.

This matters because otherwise checkpointing becomes cumbersome and agents may skip memory updates.

The intended rule:

Checkpoint approval covers the approved LOG plus warranted memory/index writes unless explicitly scoped otherwise.

This rule should not be abused. If the agent changes the substance of a memory, discovers sensitivity risk, or expands scope beyond the approved bundle, it should pause and ask again.

15. Checkpoint and handoff together

Checkpoint and handoff often run together near compaction.

A robust boundary flow looks like this:

context pressure detected
→ draft checkpoint bundle
→ draft rich handoff
→ approval
→ write memory/index updates
→ append LOG
→ write handoff
→ archive/backfill/verify
→ refresh RECENT TAIL before compaction
→ replay handoff after compaction

Each artifact has a job:

Artifact	Job
LOG	chronological audit of the checkpoint
memory files	durable reusable facts and lessons
MEMORY.md	navigable index of memory corpus
transcript archive	authoritative source history
vector/index store	recallability
handoff	immediate post-boundary resumption
recent tail	last-minute freshness before compaction

The distinction is important:

Checkpoint makes experience durable.
Handoff makes the next state effective.
Compaction changes the prompt window.
Recall retrieves what the checkpoint made findable.

16. Checkpointing in closed and semi-closed harnesses

MindStone-Agent proper can eventually own the whole prompt assembly path. When it does, sliding-window context management can keep live context bounded without relying on lossy compaction.

Coding-agent substrates are different.

Claude Code, Pi, Codex CLI, Gemini CLI, and similar harnesses may expose useful extension or hook surfaces, but they generally retain control over some combination of:

conversation storage;
prompt assembly;
native compaction;
context pruning;
model routing;
lifecycle events;
tool execution boundaries.

In those environments, MindStone cannot always enforce the ideal runtime policy.

Checkpointing becomes the portable continuity discipline:

If you cannot own the prompt window, own the durable continuity substrate.

That is why checkpointing matters for MS4CC, MS4PI, MS4Codex, and MS4Gemini.

The substrate adapter may change. The checkpoint semantics should not.

17. Implications for MS4Codex / MS4CDX

MS4Codex should treat checkpointing as a first-class lifecycle command, not as an optional session summary.

The exact hook surface will depend on Codex CLI capabilities, but the desired protocol is the same:

/checkpoint or /ms-checkpoint equivalent
→ draft LOG/memory/index bundle
→ approval gate
→ durable writes
→ transcript/session archive
→ backfill/index/embed
→ status verification

Design requirements for MS4CDX:

preserve first-person identity and user context;
maintain LOG.md, structured memory, and MEMORY.md index;
archive Codex session transcripts or equivalent message history;
provide prompt-time recall if the substrate exposes a pre-inference hook or wrapper path;
detect context pressure where possible;
write a rich handoff before compaction or restart boundaries;
run checkpoint archive/backfill explicitly rather than relying only on session exit;
record degraded behavior honestly when Codex does not expose needed lifecycle events.

If Codex cannot expose a reliable PreCompact equivalent, MS4CDX should compensate with lower warning thresholds, more frequent explicit handoffs, and end-session checkpoint discipline.

The design invariant:

Do not let Codex substrate limits turn checkpointing into a note-taking ritual.
It must still write memory, archive source history, and verify recallability.

18. Implications for MS4Gemini / MS4GMNI

MS4Gemini should follow the same checkpoint semantics while adapting to Gemini’s available CLI/session surfaces.

Expected concerns:

how session transcripts are stored or exported;
whether pre-inference context injection is available;
whether compaction or summarization events are exposed;
whether tool calls and tool results are preserved in a parseable record;
how local memory files can be loaded into the model’s context;
how to run archive/backfill safely from the harness.

Minimum viable checkpoint behavior for MS4GMNI:

1. preserve identity/user/LOG/memory file layout;
2. provide an explicit checkpoint command or documented ritual;
3. search existing memory before new memory;
4. write approved memory/index updates;
5. append LOG;
6. archive whatever transcript/session record Gemini exposes;
7. index/embed changed memory and transcript sources;
8. verify recall status or report degraded mode;
9. write handoff when compaction/restart risk exists.

If Gemini does not expose enough lifecycle control for automatic checkpoint triggers, the framework should be honest and rely on explicit user/agent commands until the substrate can support more.

The checkpoint protocol is portable because it is not tied to one hook API. It is tied to continuity semantics.

19. Relationship to consolidation cycles

Checkpointing is one governed implementation of the broader consolidation cycle.

The consolidation-cycle paper frames the larger loop:

review experience
identify durable lessons
write/update memory
append LOG
archive transcript
backfill/embed indexes
verify recall health
refresh handoff if needed

Checkpointing is the operational command form of that loop in coding-agent substrates.

Short distinction:

Consolidation cycle = the general continuity-maintenance process.
Checkpoint = the governed, explicit, user-visible implementation of that process.

In MindStone proper, some consolidation may become scheduled, backgrounded, or policy-driven. In MS4CC/MS4PI/MS4CDX/MS4GMNI, checkpointing remains important because the agent benefits from an explicit governed ritual at boundaries.

20. Relationship to sliding-window context management

Sliding-window context management and checkpointing solve different problems.

Sliding window asks:

What can leave the live prompt while preserving transcript history?

Checkpointing asks:

What should become durable continuity, and has it been verified?

A system can have sliding window without good checkpointing. It will keep the prompt bounded, but may fail to promote lessons into durable memory.

A system can have checkpointing without sliding window. This is common in closed harnesses. It can preserve memory and recall even though live context management is still compaction-based.

Together, they are stronger:

sliding window protects live context
checkpoint protects durable continuity

21. Relationship to resonance-weighted recall

Recall quality depends on checkpoint quality.

Resonance-weighted recall ranks candidates using signals such as:

semantic similarity;
source authority;
critical/evergreen status;
hits;
prevented count;
recency;
project and role relevance;
source kind;
safety constraints.

Checkpointing creates and maintains many of those signals.

Examples:

A checkpoint writes a new lesson_*.md memory.
The memory index explains when it should be used.
A future checkpoint records that it prevented a repeated mistake.
The prevented count increases.
Future recall can weight it more strongly.

Without checkpointing, recall is mostly retrieval. With checkpointing, recall becomes a way for prior operational experience to shape future judgment.

22. Source authority and claim discipline

Checkpoint artifacts are important, but they are not all equal.

Recommended source authority order:

current verified local evidence
explicit current user instruction
authoritative source files and transcripts
approved structured memory
LOG/checkpoint entries
handoff
compaction summary
inference

A checkpoint should not overclaim.

It should distinguish:

implemented
built
tested locally
verified live
pushed
reported by user
inferred
not tested
blocked
pending

This is central to MindStone’s operating discipline.

A checkpoint that says “complete” without verification creates future risk. A future agent may treat the LOG as authority and skip the validation that never happened.

The rule:

Never let a checkpoint make unverified work sound finished.

23. Safety and privacy

Checkpointing can concentrate sensitive context.

A LOG entry, memory file, or handoff may include:

personal user information;
workplace risk;
credentials boundaries;
private project details;
local file paths;
security-sensitive findings;
incident response context;
operational mistakes.

A checkpoint system should define where artifacts live and who can read them.

MindStone substrate editions keep private continuity state in local private directories rather than public package repos.

Rules:

do not commit private identity/user/log/memory/transcripts;
do not post private checkpoint content to shared channels without authorization;
do not write sensitive durable memory without approval when required;
redact or avoid secrets before embedding;
distinguish private continuity from public documentation.

The checkpoint should preserve continuity without expanding disclosure.

24. Failure modes and safeguards

24.1 LOG-only checkpoint

The agent writes a nice LOG entry but skips warranted memory files.

Safeguard:

Checkpoint is incomplete if warranted memory docs/index updates are skipped.

24.2 Duplicate memory creation

The agent writes a new memory for a lesson already captured elsewhere.

Safeguard:

Search existing memory first. Update existing memory where suitable.

24.3 Stale memory index

The memory file exists, but MEMORY.md does not point to it.

Safeguard:

New memory and index pointer are one checkpoint bundle.

24.4 Unverified recall

Memory files and LOG are written, but the vector/index backfill fails or is skipped.

Safeguard:

Run archive/backfill/status verification and record the result.

24.5 Summary masquerades as memory

A broad summary is treated as durable guidance even though the actual reusable lesson is unclear.

Safeguard:

Write focused structured memories with clear scope and source rationale.

24.6 Transcript not archived

The live session contains the authoritative source record, but it is not copied into the continuity substrate.

Safeguard:

Archive live transcript during checkpoint and before compaction where possible.

24.7 Expensive embedding runs too often

The system re-embeds large transcripts every turn and degrades local performance.

Safeguard:

Archive cheaply and often; embed at checkpoint/post-compaction boundaries.

24.8 Approval ambiguity

The user approves the LOG but the agent is unsure whether memory writes are included.

Safeguard:

Draft the checkpoint bundle clearly. State that approval covers LOG plus warranted memory/index writes unless narrowed.

24.9 Untracked local artifacts forgotten

A checkpoint fails to record that important source drafts are local/untracked.

Safeguard:

Include repo status and untracked/protected files under drift or open threads.

24.10 Overclaiming substrate parity

The checkpoint says a port is fully working when only the shape is implemented.

Safeguard:

Record validation status precisely. Implemented/scaffolded is not proven.

25. Operational checklist

A practical checkpoint should answer these questions.

What happened?

What work was completed?
What files changed?
What commits were made?
What commands were run?
What tests/builds/verifications passed?
What remains unverified?

What decisions were made?

Architecture decision?
Product positioning decision?
Public documentation decision?
Safety/privacy decision?
Substrate adapter decision?

What should become durable memory?

New project fact?
New design rule?
New lesson?
New user preference?
New limitation?
New source-of-truth pointer?

Does a similar memory already exist?

Search memory first.
Update existing memory when possible.
Create a new memory only when distinct.

What should be logged but not memorized?

Not every detail deserves durable structured memory.

A checkpoint should be selective.

What drift remains?

Role drift?
Validation gap?
Repo status issue?
Unresolved incident?
Unfinished follow-up?
Contradictory memories?

Did the mechanics land?

Transcript archived?
Memory indexed?
Transcript chunks indexed?
Embeddings succeeded?
Recall status checked?
Errors recorded?

Is a handoff needed?

If compaction, restart, or transfer is possible, checkpoint should coordinate with handoff.

26. Evaluation checklist

A checkpoint protocol should be evaluated by future behavior, not by how polished the LOG entry looks.

Durability

Did important lessons become structured memory?
Were existing memories updated instead of duplicated?
Is the memory index accurate?
Is the transcript archived?

Recallability

Were memory/transcript chunks indexed?
Did recall status report semantic mode or degraded mode honestly?
Were errors surfaced?
Can a future prompt find the new memory?

Governance

Was approval required and respected?
Were sensitive facts handled safely?
Were identity/user edits protected?
Was scope expansion avoided?

Auditability

Does LOG show what happened?
Does it name decisions and drift?
Does it record verification results?
Can a future agent trace a memory back to the session context?

Behavioral improvement

Does the checkpoint help avoid a repeated mistake?
Does it preserve a user correction?
Does it sharpen project judgment?
Does it improve future calibration around tested vs untested work?

Boundary robustness

If compaction happens, is handoff ready?
Was recent tail refreshed?
Will post-compaction replay have enough context?
Did deferred backfill run?

27. Reference implementation sketch

A checkpoint can be modeled as:

function checkpoint(session):
    recent = loadRecentTranscript(session)
    citedMemories = detectCitedMemories(recent)
    durableCandidates = synthesizeDurableCandidates(recent)

    existingMatches = searchMemory(durableCandidates)
    memoryPlan = decideCreateOrUpdate(durableCandidates, existingMatches)

    logEntry = draftLogEntry({
        whatHappened,
        decisions,
        memoriesCited,
        preventedConfirmations,
        newMemories: memoryPlan,
        drift,
        lint
    })

    bundle = {
        logEntry,
        memoryFilesOrUpdates: memoryPlan.files,
        memoryIndexUpdates: memoryPlan.indexEntries,
        handoffIfNeeded
    }

    approval = requestApproval(bundle)
    if not approval:
        return { status: "draft-only" }

    writeMemoryFiles(memoryPlan)
    updateMemoryIndex(memoryPlan)
    appendLog(logEntry)
    writeHandoffIfApproved(handoffIfNeeded)

    archive = archiveLiveTranscript(session)
    backfill = indexMemoryAndTranscripts()
    recallStatus = verifyRecallStatus()

    appendOrReportVerification({ archive, backfill, recallStatus })

    return {
        status: "complete" if recallStatus.ok else "degraded",
        archive,
        backfill,
        recallStatus
    }

For MS4CC specifically:

CAIRN_CHECKPOINT_MODE=1 orchestrator/.venv/bin/python orchestrator/hooks/session_end.py < /dev/null

For MS4PI specifically, the equivalent explicit mechanical path is:

/ms-recall-backfill

or:

/ms-end-session

with status checked afterward.

The implementation can vary, but the invariants should remain:

search before memory
approve before durable writes
write memory before LOG completion
archive transcript
backfill/embed
verify status
record failures honestly

28. Conclusion

Checkpointing is the MindStone discipline that prevents experience from evaporating into transcript history or flattening into summaries.

It is not a save point. It is not a generic summary. It is not handoff. It is not compaction. It is not vectorization alone.

A checkpoint is governed continuity promotion plus verification.

It reviews recent operational experience, decides what should become durable, updates structured memory and indexes, appends the LOG, archives the transcript, backfills recall, and records whether the substrate is healthy.

That is why checkpointing is crucial for MS4CC and MS4PI, and why it should be carried forward into MS4Codex/MS4CDX and MS4Gemini/MS4GMNI.

Closed and semi-closed coding-agent substrates will differ in hooks, commands, transcript storage, and compaction events. The checkpoint protocol gives MindStone a portable way to preserve continuity despite those differences.

The durable rule:

Do not merely summarize the session.
Decide what the agent should learn, write it where it belongs, and prove it can be recalled.

Short version

A MindStone checkpoint is a governed continuity cycle.

It works like this:

synthesize the session
identify decisions and lessons
search existing memory
update or create structured memory
update MEMORY.md
append LOG
archive transcript
backfill/embed indexes
verify recall status
record drift and failures
write handoff if a boundary is near

Key distinctions:

Summary says what happened.
Handoff prepares the next state.
Compaction changes the live prompt.
Recall retrieves relevant past context.
Consolidation is the broader maintenance cycle.
Checkpoint is the governed command/process that makes experience durable and verifies it landed.

In MS4CC, this is /checkpoint. In MS4PI, it is /ms-checkpoint. In MS4Codex/MS4CDX and MS4Gemini/MS4GMNI, the adapter surfaces may differ, but the semantics should remain the same.

A checkpoint is complete only when both meaning and mechanics land:

durable memory and LOG updated when warranted
+ transcript archived
+ index/backfill/embed verified
+ status recorded honestly