Reference: Memory

Reference for the "Memory" group of qargi commands: every verb with its arguments, options and examples, generated from the release.

Updated 2026-11-05

qargi memory #

Check a memory store, list its tiers, read a note, split, merge or copy stores.

split, merge and copy work between two stores, each a directory of notes, a .jsonl dump (read-only: a source, never a target) or a memstore_ id. A note with a name starting with a dot, or that a store cannot hold, makes the plan refuse and name it. Nothing is deleted: what a split moves out of a store goes to /_archive/<date>/ and a collision to /_conflicts/<date>/, and the origin of every note written is added to its Sources: line, so each change can be undone. Without --approved they print the plan and its token and change nothing; a store whose notes changed since the plan is refused.

Verb	What it does
`lint`	Check a store against the canon
`get`	Print one note
`tiers`	List the project's memory tiers (repo, cloud, project, shared, system): where each is, whether it exists, its notes
`check`	Check every existing memory tier against the canon, and that no note lives in two tiers
`init`	Create a memory tier (repo, project, shared or system) as an empty store of the standard layout
`move`	Move notes from one tier to another, with the original archived in the first
`split`	Copy the notes a selector picks into another store, optionally archiving the originals
`merge`	Add every note of FROM that TO lacks
`copy`	Copy notes into another store, leaving the source as it is

qargi memory lint #

qargi memory lint STORE_ID [OPTIONS]

Check a store against the canon.

Option	Argument	What it does
`--kind`	`KIND`	recipes or reference (for a store before the canon)

qargi memory get #

qargi memory get STORE_ID PATH

Print one note.

qargi memory get memstore_01ABC /shared/INDEX.md

qargi memory tiers #

qargi memory tiers [OPTIONS]

List the project's memory tiers (repo, cloud, project, shared, system): where each is, whether it exists, its notes.

A tier is one memory store of the standard layout at a fixed rank, highest first: repo > cloud > project > shared > system. Where they are comes from the project's answers (memory.tiers; each key is optional and has a default). The reference store is not a tier. Reads only; nothing is created or changed.

Option	Argument	What it does
`--project`	`PROJECT`	the project, instead of the one inferred from here
`--json`		machine-readable

qargi memory check #

qargi memory check [OPTIONS]

Check every existing memory tier against the canon, and that no note lives in two tiers.

Runs the canon check on each tier that exists, then reports a note path present in two or more tiers (structural files such as README.md and INDEX.md repeat per tier and are fine). A tier that does not exist (memory init creates it) or cannot be reached is information, not a failure. Exit 1 when anything failed.

Option	Argument	What it does
`--project`	`PROJECT`	the project, instead of the one inferred from here

qargi memory init #

qargi memory init TIER [OPTIONS]

Create a memory tier (repo, project, shared or system) as an empty store of the standard layout.

Without --approved it shows what would be created and a plan token and changes nothing. It refuses a tier that holds files that are not a standard store, one whose place overlaps another tier, a repo tier outside the checkout, and the cloud tier (provision creates that). The repo tier is written inside your repository checkout: qargi never commits it, so review it and commit or ignore it yourself. A tier that is already set up says so and exits 0.

Option	Argument	What it does
`--project`	`PROJECT`	the project, instead of the one inferred from here
`--plan`	`TOKEN`	the plan token printed by the same command without --approved
`--approved`	`WORDS`	your go-ahead for exactly that plan, in your words; recorded in the audit log

qargi memory move #

qargi memory move PATH [OPTIONS]

Move notes from one tier to another, with the original archived in the first.

PATH is one note (ending in .md) or a folder prefix under shared/ or roles/ROLE/. Only notes move, never indexes. A note must live in one tier, so it refuses a path that is also in another tier. Nothing is deleted: the original goes to /_archive/<date>/ of the first tier and each copy records its origin. Without --approved it prints the plan and its token and changes nothing; a tier whose notes changed since the plan is refused.

Option	Argument	What it does
`--project`	`PROJECT`	the project, instead of the one inferred from here
`--from`	`TIER`	the tier the notes are in
`--to`	`TIER`	the tier they go to
`--plan`	`TOKEN`	the plan token printed by the same command without --approved
`--approved`	`WORDS`	your go-ahead for exactly that plan, in your words; recorded in the audit log

qargi memory split #

qargi memory split FROM TO [OPTIONS]

Copy the notes a selector picks into another store, optionally archiving the originals.

At least one of --prefix, --role and --note-kind is needed; a note must match every one given. Notes already in TO are left; a different one goes to /_conflicts/<date>/ in TO.

Option	Argument	What it does
`--prefix`	`PATH`	pick the notes under this path (repeat for several)
`--role`	`ROLE`	pick the notes under /roles/ROLE/
`--note-kind`	`KIND`	pick the notes whose Kind: header is KIND (setup, gate, rule, ...)
`--archive`		move the originals to /_archive/<date>/ in FROM (with their origin in Sources:)
`--plan`	`TOKEN`	the plan token printed by the same command without --approved
`--approved`	`WORDS`	your go-ahead for exactly that plan, in your words; recorded in the audit log

qargi memory split ./memory ./build --role build --archive
qargi memory split ./memory ./build --role build --archive --plan TOKEN --approved "go"

qargi memory merge #

qargi memory merge FROM TO [OPTIONS]

Add every note of FROM that TO lacks.

FROM is only read. A note whose original sits in TO's archive is moved back from it, so merging what a split wrote undoes the split.

Option	Argument	What it does
`--policy`	`POLICY`	what to do when a note differs: conflicts (put the incoming one in /_conflicts/<date>/, default) or keep (leave it and report)
`--plan`	`TOKEN`	the plan token printed by the same command without --approved
`--approved`	`WORDS`	your go-ahead for exactly that plan, in your words; recorded in the audit log

qargi memory merge ./build ./memory

qargi memory copy #

qargi memory copy FROM TO [OPTIONS]

Copy notes into another store, leaving the source as it is.

Without a selector every note is copied except /CANON.md. Each copy records its origin in Sources:.

Option	Argument	What it does
`--prefix`	`PATH`	pick the notes under this path (repeat for several)
`--role`	`ROLE`	pick the notes under /roles/ROLE/
`--note-kind`	`KIND`	pick the notes whose Kind: header is KIND (setup, gate, rule, ...)
`--policy`	`POLICY`	what to do when a note differs: conflicts (put the incoming one in /_conflicts/<date>/, default) or keep (leave it and report)
`--plan`	`TOKEN`	the plan token printed by the same command without --approved
`--approved`	`WORDS`	your go-ahead for exactly that plan, in your words; recorded in the audit log

qargi canon #

Bring a project's two memory stores to the standard layout and keep them there.

The canon fixes the layout and the note format of both stores (shared/ and roles/<role>/, a header on every note, an index with a Load column). plan and apply set up an empty store and keep a current one current; a store of an older layout or canon version is reported as unknown and not changed.

Verb	What it does
`check`	Report conformance and the version of each store
`plan`	Print every step needed to reach the current canon (changes nothing)
`apply`	Run the plan
`seed-role`	Write a role's baseline notes without overwriting anything
`promote`	Move a role's note to shared/
`audit`	Report a session that wrote under another role's folder