Why maxims

An agent can hold a rule in its memory and still not act on it, because memory bodies load on recall and recall is probabilistic. maxims puts each rule's one-line summary in the layer the agent loads every session and leaves the body on disk behind a pointer. This page is the reasoning; the quickstart is the commands, and how it works is the mechanism.

The rule the agent held but did not act on

The failure this tool exists for is a rule that sits in a memory file while the sessions it was written for keep breaking it: a "give every call a timeout" rule, and the calls still went out bare. The memory system had the rule. The session did not.

Before, the rule lived in a memory directory the agent searched only when it judged the memory relevant:

~/.claude/projects/<project>/memory/prefer-timeouts-to-hangs.md
   loaded:  when the agent decides to look        (recall, probabilistic)
   result:  a session that never looked sent the call bare

After, the same rule's one-liner sits in the rules layer the harness reads at launch, and the body lives in the store, the hash illustrative:

~/.claude/rules/maxims-octocat-rules.md
   - A timeout on EVERY call that leaves the process, however short.
     (detail: ~/.agents/maxims/store/octocat/rules/memories/prefer-timeouts-to-hangs.md, a1b2c3d)
   loaded:  at every session start                 (guaranteed)
   result:  every session opens already holding the rule

The body's content is unchanged; its home is now the store. Only the one line that must always be present changed layers.

The npx skills analogy

npx skills             : repo of skills   -> agent's skill dirs   (on-demand workflows)
npx -y @vivswan/maxims : repo of memories -> agent's rules layer  (always-on one-liners)

Both install a versioned GitHub repo like a package, with selection, state, and removal; the difference is the target layer.

• Skill dirs are the probabilistic layer maxims is escaping. Skills load when invoked or judged relevant.
• The rules layer is always loaded. Every harness on the harnesses page has one, and having one is what qualifies it for a row.

Rules also come from reviewable repos instead of hand-copied files, so one machine cannot silently drift from another, and a hook re-syncs them at every session start.

Prior art

Each tool below already solved part of the problem. The table says what maxims copied from it and what it left behind; the notes under it say what each tool does and where the line falls.

tool or practice	what maxims took	what maxims left
npx skills (vercel-labs/skills)	the verbs, the flags, @owner/repo, ~/.agents/, the committed lock	the skills layer itself
Claude Code's MEMORY.md index	the two layers, the memory file format	the single harness and the single folder
rulesync (dyoshikawa/rulesync)	the fan-out, one source in each harness's own format	the unit and the trigger
a shell rc line, an OS scheduler, an editor folder-open task, a git hook	nothing	all four

• npx skills installs SKILL.md folders from a GitHub repo into each agent's skills directory, with add, list, remove, and update, and a committed skills-lock.json a fresh clone replays. maxims takes its flag names and short forms, and the project lock mirrors its lock. What skills do not have is the rule line in the always-loaded layer and the session-start hook that re-syncs it.
• Claude Code's MEMORY.md index is one index file, loaded every session, with one line per memory that points at the body file beside it. Taking its format means a source repo needs no new one. maxims writes the index for every harness in the matrix, from a source repo, and leaves Claude Code's own memory folder to Claude Code.
• rulesync compiles rule files under .rulesync/ into the native rule format of each supported agent when you run rulesync generate. maxims installs published memories from a repo rather than compiling your own local files, and a hook re-syncs at session start rather than a generate step you run by hand.
• A shell rc line, an OS scheduler, an editor folder-open task, or a git hook refreshes a file from outside the agent, on a shell start, a clock, an editor open, or a commit. None fires on the agent's session start, so a session can still open on a stale file; the freshness fallbacks decision records the rest of the reasons.

What a rule costs

item	cost
one rule line in the rule file	about 25 tokens, loaded every session
the memory body	zero tokens until an agent opens the file
a source at the default rule cap	about 600 to 700 tokens