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

magus-notes

Human-authored notes committed to the repository

Synopsis

magus notes <ls|get|edit|verify|capture|promote> [flags]

Description

Read the workspace's human-authored notes.

A note carries knowledge whose only provenance is a person: something no extractor could derive from the tree, and that no rebuild would recover. That is what separates it from the two things it is NOT. Documentation describes the system for a reader and lives in the docs tree. A NOTE/WHY/TODO comment marks one location in one file. A note attaches to graph ENTITIES - a symbol, a file, a project, a target, another note - and may span several at once, which is how it can record something like "these two caches must be invalidated together" that no single comment could hold.

Anchors are required, and they name node IDs rather than positions. A symbol anchor survives the code moving file and line and breaks only on a rename or a deletion, which is exactly when the note should be re-read; a line number would break on the next edit above it with nothing to detect.

There is no put. Notes are written by a person in their own editor and committed under their own name, which is what makes git attribution meaningful and what keeps the store worth trusting. Set knowledge.notes.path in magus.yaml to declare where they live; with nothing declared the feature is inert.

notes capture options

--name string
Note name (defaults to review-<patch digest>)
--private
Only your own notes (default for capture)
--shared
Only notes committed to this repository (your team has these)
--tag string
Tag to set on the note; repeatable
--title string
Title for the note (defaults to naming the reviewed base)

notes promote options

--name string
Note name (defaults to the record's name)

Subcommands

ls
Show notes and any repair warnings
get
Show one note
edit
Open one note in $VISUAL or $EDITOR
verify
Check malformed notes and anchors that no longer resolve
capture
Capture the review under way as a note: your own remarks plus any colleagues' comments
promote
Open an agent-drafted memory record for editing and write it to the shared notes store under your own name

Examples

List every note

magus notes ls

Read one note

magus notes get cache-invalidation-pairing

Write or revise one

magus notes edit cache-invalidation-pairing

Check every anchor still resolves

magus notes verify

Capture the review under way

magus notes capture

Promote a memory record into a shared note

magus notes promote release-checklist

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-memory(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. ChangelogEvery released change to magus, newest first, in Keep a Changelog format. Generated from releases/*.yaml. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect.
generatedinternal/cli/registry.goclimagus notesnotesknowledgeannotations
Last updated (4f8cc295)
Earlier changes on this page (6)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

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.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

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

Span

OpenTelemetry's name for one unit of work under a trace - a target execution, whose sub-operations are child spans. An output reference points at a span's captured output. See telemetry.

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.