magus v0.4.2 is out. See what's new
¶ View generated markdown
2 min read

magus-memory

Durable cross-session project memory

Synopsis

magus memory <ls|get|put|delete|verify> [flags]

Description

Manage the per-repository handoff journal, which is stored outside the checkout so it survives worktrees and branch switches.

Entries are visible to people and to agents across sessions. They are NOT automatic model memory: nothing writes one for you, and nothing is recalled implicitly. An entry earns its place when a later reader needs to reopen the evidence behind a decision - the run, the query, the output reference, the document - rather than to be told a conclusion.

An elimination entry records what an investigation ruled OUT: the hypothesis, why it is dead, and an excerpt of the evidence that killed it. The excerpt is required because an output reference resolves only from the checkout that produced it, which leaves the ref beside it a best-effort handle.

put creates an entry, and on one that already exists it writes only the fields you pass. Omitting a flag keeps what is stored, so refreshing a status cannot drop the body beside it - the store keeps no history and there would be nothing to restore it from. The cost is that an omitted flag cannot CLEAR a field either; delete the entry and create it again for that. Pass --amend to require the name to exist, and change a record's type by deleting and recreating it.

verify is the maintenance verb: it reports entries that are malformed, stale, that link to something no longer there, or whose evidence no longer resolves. The same entries are reachable through the magus_memory MCP tool and the console, so a journal written from the CLI is readable by an agent without either side learning a new format.

memory put options

--amend
Require the entry to exist: refuse a name the journal does not hold instead of creating it
--body string
Short why/caption, decision, plan and elimination only
--excerpt string
The evidence that ruled a hypothesis out, copied inline; elimination only and required there
--ref string
Entry ref in 'kind: target' form; repeat for multiple refs
--reference string
Name of another entry this one relates to; repeat as needed
--status string
Lifecycle label, e.g. accepted, active, done, stale
--type string
Entry type: pointer, decision, plan, or elimination. Required to create; on an existing entry it must match the type already stored

Subcommands

ls
Show entries and any repair warnings
get
Show one entry
put
Create a named entry, or update the fields you name on one
delete
Remove one entry
verify
Check malformed, stale, broken-linked, and unresolvable-evidence entries

Examples

List entries and warnings

magus memory ls

Read one entry

magus memory get release-checklist

Record what an investigation ruled out

magus memory put resize-bar-misreported --type elimination --ref 'output: out1a2b3c' --body 'Not the BIOS: the aperture is reported correctly.' --excerpt 'BAR0: 256M ...'

Refresh one field and keep the rest

magus memory put release-checklist --amend --status done

Check the journal's health

magus memory verify

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(1), magus-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-vcs(1), magus-doctor(1), magus-config(1), magus-session(1), magus-notes(1), magus-diff(1), magus-server(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-agent(1), magus-self(1), magus-version(1)

ManpagePages in this section. magus-runRun builds, tests, lints, and codegen through magus targets. ChangelogEvery released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml. ScopeThe claim magus is built on - that a correct incremental build already requires a precise model of your repo, and everything else is a read of it. Includes the test for what belongs, the boundaries, and where the claim is strained.
generatedinternal/cli/registry.goclimagus memoryhandoffjournalagents
Last updated (77dde07d)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Output reference

A short, shareable id (out1a2b3c, "ref" for short) for one target execution's captured output; it appears on each target's line, and magus query output out1a2b3c prints those exact bytes. In OpenTelemetry terms it corresponds to a span (one target execution) within its trace (the whole magus invocation). See output-refs.

Health

The at-a-glance daemon state derived from the pool: healthy when the pool is reporting, degraded when it reports an error, down when there is no pool. The dashboard color-codes each state. See daemon.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Session

One magus process's recorded facts - the targets it finished, their outcomes, and the lease it acted as - kept in a repo-scoped store every worktree shares. magus session lists them; the store prunes itself by last-fact age.

Lease

One row of the lease ledger: a piece of work an orchestrating agent handed out, with its goal, the checkpoint it was cut against, and the paths it owns or must not touch. The ledger records; the agent guard is what reads those facts back when grading a write. See doctrine.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.