Keep project memory

Memory keeps a project's decisions, open work, and evidence as stones. A stone is a Markdown record that ksmem validates on every write. The name is unique to Keystone, so "stone" always means this kind of record. For the ideas behind stones, see Memory and context.

Start each session

Run this command at the start of each session:

ksmem show context

The output lists active work, recent closures, stale items, and the next commands. Your agent can run it too. Connect your coding agent shows the line to add to AGENTS.md.

Set up storage the first time

Memory needs a place to store stones. If a project has no store yet, the first write stops and prints the command to run.

To set up the store before the first write, run one of these commands:

# Attached: keep memory in a capsule outside the repository
ksmem --repo . --capsule ~/.keystone/capsules/<repo-slug>-<hash> init

# Published: keep memory in the repository, under .keystone/
ksmem init --published

Record work

1. Create a stone:

   ksmem add stone --domain shared --type decision --priority p1 \
     --title "Move export jobs to the durable job queue"

2. As the work moves, add notes. A note goes to the journal unless you name a different section:

   echo "Benchmarked both queues; the durable queue adds 4 ms per job." | ksmem note stone k3v9qa
   echo "Use the durable queue for every export job." | ksmem note stone k3v9qa --section decisions

To see the stone types your project allows, and the sections each type has, run ksmem show types.

Find what the project knows

ksmem search stones "export queue"   # search stone text
ksmem list stones --domain shared    # list shared stones
ksmem show stone k3v9qa              # read one stone
ksmem deps stone k3v9qa              # show what it depends on
ksmem ready stones                   # show open work whose dependencies are met

Check a stone before you hand it off

Before an agent implements a stone, make sure the stone has enough detail:

ksmem show readiness k3v9qa

The report looks for a definition of done, the planned changes, validation steps, and other evidence. It marks each one present, missing, or unclear, and quotes where it found it. The report shows what the stone says. You decide if the plan is good.

Finish work

When the work is done, validate and close the stone:

ksmem validate --since-last && ksmem close stone k3v9qa --lesson "Measure queue latency before choosing a queue."

If you stop before the work is done, record the reason for the next session:

echo "Open because: waiting on the load test" | ksmem note stone k3v9qa

Capture quick notes

Keep stones valid

Change stones only with ksmem commands, because direct edits skip validation. To find problems, run ksmem validate. It also reports dependencies that do not resolve.