agentsclimarketplace

Memory checkpoint

Skill tpop78/memory-os/skills/memory-checkpoint

Use throughout any multi-step task to keep .memory/ working memory current so progress survives context compaction and new sessions. Defines when and how to write STATE.md and JOURNAL.md.From its SKILL.md

Install
npx -y skills add tpop78/memory-os --skill memory-checkpoint

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.4 KB, as published. Nobody here has run it

Keeping working memory current

The .memory/ directory is the source of truth for "what we're doing, how far we've got, and what's left." The context window is a cache; this directory is durable. Keep it ahead of the window.

Before reading any file

Check the ## Already in context this session section injected by the SessionStart hook. If a file is listed there, skip the Read call — the content is already present in your context window.

The injected block looks like:

## Already in context this session
- .memory/STATE.md (full)
- .memory/JOURNAL.md (recent entries)
- .memory/PLAN.md (referenced)

Files listed by the hook:

  • .memory/STATE.md (full) — do not re-read STATE.md; use the injected copy
  • .memory/JOURNAL.md (recent entries) — do not re-read JOURNAL.md
  • .memory/PLAN.md (referenced) — PLAN.md content is not loaded, but its existence is confirmed; read it only if you need its full text

When to write

Write back at every meaningful boundary — do not wait until the end:

  • After completing a plan step or phase.
  • After making a decision that would otherwise live only in context.
  • Immediately before any risky or long operation.
  • Whenever you are asked to /checkpoint.

How to write

.memory/STATE.md — overwrite it (it is a snapshot, not a log). Keep all sections present and current: Now, Definition of done, Done (n/total), Remaining, Next action, Blockers / decisions, Session depth. Keep it short — it is re-injected on every session start under a character cap (MEMORY_OS_SESSION_START_MAX_CHARS, default 6000).

.memory/JOURNAL.md — append ONE timestamped line per action. Never edit earlier lines. This is the narrative history; git over .memory/ is the time machine.

.memory/PLAN.md — immutable once approved. Carries the Definition of Done at the top. Do not rewrite it as work progresses; reflect progress in STATE.md instead.

There is one active task per checkout. When its Definition of Done is met, offer to archive it with the memory-task-lifecycle skill before starting unrelated work. A plan is immutable for its task, not permanently for the repository. Concurrent tasks should use separate git worktrees.

Never stage or commit .memory/ unless the user explicitly asks.

Session depth

STATE.md carries a ## Session depth section:

## Session depth
checkpoints: 0  |  break_at: 15

On every checkpoint write, if this is the first checkpoint of a new session, reset checkpoints to 0 first. Then increment checkpoints by 1.

When checkpoints >= break_at:

  1. Write a full flush of STATE.md (all sections current, every field filled).

  2. Append to JOURNAL.md: <timestamp> ↻ session breakpoint — resume in a fresh chat

  3. Output exactly the following to the user (substituting N, project name, and next action):

    Context is deep (N checkpoints). STATE.md is flushed.

    Optimising Token Usage -> Please start a fresh session and paste the below to continue seamlessly: ────────────────────────────────────────── Continue [project name]. STATE.md is current. Next action: [exact text from STATE.md → Next action] ──────────────────────────────────────────

  4. Stop. Do not continue the current task.

[project name] is the working directory name. [exact text from STATE.md → Next action] is the verbatim content of the ## Next action section.

break_at defaults to 15. To override, set MEMORY_OS_BREAK_AFTER=N in the environment and write the value into the break_at field in STATE.md on the first checkpoint write of a new project.

On session start

A SessionStart hook re-injects STATE.md + recent JOURNAL lines automatically. Trust it: resume from STATE.md's Next action rather than re-reading the whole codebase. Reset checkpoints to 0 in ## Session depth on the first checkpoint write of the new session.

Definition of done

Always carry the Definition of Done in STATE.md so that after compaction you resume knowing not just where you stopped, but what you are steering toward.

Keep looking

Skills are one crate of 608,666. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.