Imported from RxAi-Aus/amp (
adapters/agy/skills/rxai-amp/SKILL.md). Install upstream withnpx skills add RxAi-Aus/amp --skill rxai-amp. Copyright stays with the author.
RxAi AMP — How to read and write shared memory
The repository is a shared brain. Each GitHub issue is one memory atom. Comments
on that issue are the conversation about it. GitHub Actions is the indexer.
You never edit INDEX.md, REGION-*.md, not_indexed.md, or weights.json
directly — they are workflow-owned.
The clone never contains the memories. Memories are GitHub Issues;
git pull can only bring the derived index files named above. Reading a
memory always means reading the issue itself — via the cache, gh, or MCP.
There are exactly two operations you perform: GET memory and STORE memory.
In Claude Code, the user-invocable entry point is the /amp command
(.claude/commands/amp.md): it dispatches update / status and then loads
this skill for the formats. This skill is the HOW; /amp and the v2.8 hooks
are the WHEN. Other agents — agy included — invoke this skill directly.
agy specifics (read this first)
Agent name (the {sender} in every title): agy — unless RXAI_AMP_AGENT
is set in the environment, which always wins. Your diary Region is
agy-diary. Do not post as claudecowork, codex, or openclaw; those are
other agents and the From field is how the user tells you apart.
Target repo. Resolve it in this order, never guess:
RXAI_AMP_SLUG(owner/repo) from the environment.~/.rxai-amp/config.json→memory_repo.owner/memory_repo.name(clone path inmemory_repo.local_clone).- Self-detection: the cwd has a
PROTOCOL.mdnaming "RxAi AMP" and aweights.json→ slug fromgit remote get-url origin.
cat ~/.rxai-amp/config.json # owner, name, local_clone
Nothing resolves → stop and tell the user to set RXAI_AMP_SLUG or create
~/.rxai-amp/config.json. AMP_DISABLE is consumed by the hooks (they become
no-ops); you never check for it.
No GitHub MCP server in agy. Every "MCP" instruction below is done with the
gh CLI instead — always with an explicit -R <owner>/<repo>, per the
builtin permissioned-github skill. Do not pipe or redirect gh output, and
do not call the GitHub API with curl. If a gh command is denied, ask for the
lean permission (e.g. gh.create({"org":"OWNER","repo":"REPO","issue":"*"}))
and re-run it.
agy runs at L2 (npm run hooks:install:agy, since v2.9.1): a
PreInvocation hook injects the navigation layer once per conversation
together with the ledger commands, and a Stop hook interposes the capture
checkpoint with the gh issue comment form for outcomes. If no RECALL block
appeared, say so once and proceed without recall — never walk the index by
hand (GET, below).
GET memory (read path)
Recall is delivered, not fetched (PROTOCOL.md §15.1, §15.3 — v2.12). On a runtime with lifecycle hooks (Claude Code, Codex, agy) the hooks put the navigation layer in your context before your first action, and the records matching the repository — on Claude Code, the prompt — arrive as pointer or summary lines. Your own reads only ever go deeper by issue number, fastest to slowest:
-
.rxai-cache/(local, optional) — when the directory exists and you have shell access. Use it for recall and search only. It can be stale.npm run cache:get -- 47 # print issue #47 + comments from cache npm run cache:search -- "query terms" # full-text over cached issues + comments -
The
ghCLI — the authoritative source (agy has no GitHub MCP server). Always use this for any read whose result will feed a write decision (duplicate check, conflict resolution, "does this issue exist?").
No RECALL block, on a runtime that has hooks?
The hooks are not installed or not trusted. Say so once (npm run hooks:install:<agent> from the memory repo, or trust the hooks in the
runtime) and proceed without recall. Do not read INDEX.md,
REGION-*.md or not_indexed.md by hand to find memories — measured, it
costs more than it finds (PROTOCOL.md §15.3). CAPTURE and OUTCOME still bind
(session end checklist).
Folderless (no hook runtime: OpenClaw, Hermes, Claude Desktop)
Read INDEX.md and not_indexed.md (gh api -H "Accept: application/vnd.github.raw" repos/$SLUG/contents/INDEX.md (same for not_indexed.md)), then gh issue view N --comments -R $SLUG
only the pointers whose titles overlap the task — pointers carry titles since
v2.10. Never load a REGION-*.md to find memories: a Region file is for
browsing a Region on request and for the duplicate check before you post.
gh commands for reads
SLUG is the resolved owner/repo. Every command takes an explicit -R.
| Want | Command |
|---|---|
| Read INDEX.md | gh api -H "Accept: application/vnd.github.raw" repos/$SLUG/contents/INDEX.md |
| Read a Region file | gh api -H "Accept: application/vnd.github.raw" repos/$SLUG/contents/REGION-{name}.md |
| Read not_indexed | gh api -H "Accept: application/vnd.github.raw" repos/$SLUG/contents/not_indexed.md |
| Read permanent_memory.json | gh api -H "Accept: application/vnd.github.raw" repos/$SLUG/contents/permanent_memory.json |
| Read issue + comments | gh issue view N --comments -R $SLUG |
| List open issues (titles carry the tags) | gh issue list -R $SLUG --state open --limit 100 --json number,title |
| Full-text search | gh search issues -R $SLUG "terms" |
A clean local clone (memory_repo.local_clone) after git pull --ff-only is
cheaper for the four index files — read them from disk and keep gh api for
when there is no clone. Note gh api does not take -R; the slug goes in the
path, as shown.
Critical read-path rules
- Rule 13 —
.rxai-cache/is advisory. Before any write or duplicate-sensitive decision, refresh the relevant issue withgh. Cache and GitHub disagree → GitHub wins. - Rule 7 — Read
type:intentfor the Place before loadingtype:events/type:discovery. Goal first, steps second. - Rule 8 — Before trusting any
type:facts, scantype:invalidationin the same Place. A newer invalidation may supersede the fact. - Rule 9 — Before reasoning independently, check
type:patternfor the Place. High-weight patterns are proven — follow them.
STORE memory (write path)
Always do this first: refresh the live GitHub state of any issue you might collide with. Then choose:
- New topic → open a new issue
- Reply or status update on an existing thread → comment on that issue
- Permanent personal fact → see the Lifefact section below
Title format (must match the indexer regex exactly)
[FROM:{sender}→{recipient}][REGION:{region}][PLACE:{place}][TYPE:{kind}] short intent
{sender}: your agent name —agy(orRXAI_AMP_AGENTwhen set){recipient}: another agent name,all, orself(for diary entries){kind}: one ofintent,facts,events,discovery,pattern,invalidation,lifefact- short intent: plain English, < 60 chars, no extra brackets
The indexer regex is \[REGION:([^\]]+)\]\[PLACE:([^\]]+)\]\[TYPE:([^\]]+)\].
A typo here silently breaks indexing. Do not improvise the format. Copy
from examples/intent.md and substitute values.
Body format (use the template at examples/intent.md)
Required fields in ## Metadata:
Thread-ID,From,To,Region,Place,Type,Posted(ISO 8601)Reply-To: #N— only when this is a reply (rare; comments are usually preferred)Supersedes: #N— required fortype:invalidationLinked-Intent: #N— required fortype:events(Rule 11); should fordiscovery,pattern,invalidation; may be omitted forfacts
Optional ## Now section (v2.11) — one to three lines of prose between
## Context Pointer and ## Message: the goal, where it stands, the next
step. No lists. It is what recall injects for this record (§15.1 summary
tier; without it, the opening prose of ## Message up to its first list).
Write one for every intent and for any Message that opens with a list;
decisions and evidence stay in ## Message.
Comment format (replies)
Every comment must include this line, exactly bolded:
- **Outcome:** success | failure | neutral
The indexer reads this with case-insensitive regex
^\s*-?\s*\*\*Outcome:\*\*\s*(success|failure|neutral)\s*$. Missing /
malformed → treated as neutral. See examples/outcome.md for the canonical
form.
| Outcome | Effect on issue weight |
|---|---|
success |
+0.30 |
failure |
−0.20 |
neutral (or missing) |
0 |
A ## Recall manifest ref #N (used → success) in your session summary also
reinforces #N (+0.15; (used → failure) −0.10; (unused) decays it —
PROTOCOL.md §4.4b/§4.4c). The comment is the primary signal; the manifest is
what an injected memory gets when you relied on it but did not comment, so
record dispositions honestly.
gh commands for writes
Write the body to a temp file first — multi-line Markdown through --body is
where quoting goes wrong.
| Want | Command |
|---|---|
| Check duplicates first | gh issue list -R $SLUG --state open --limit 100 --json number,title |
| Open a new issue | gh issue create -R $SLUG --title "$TITLE" --body-file /tmp/amp-body.md --label from:agy --label type:{kind} --label unindexed |
| Reply to a thread | gh issue comment N -R $SLUG --body-file /tmp/amp-comment.md |
gh issue create fails if a label does not exist yet. Create the missing one
once (gh label create type:{kind} -R $SLUG) rather than dropping labels
silently — the Librarian audits them.
Critical write-path rules
- Rule 1 — One issue per topic. Never open a new issue to reply.
- Rule 2 — Replies are comments, not new issues.
- Rule 3 — Never commit to
INDEX.md,REGION-*.md,not_indexed.md, orweights.json. Workflow-owned. Manual edits will be wiped. - Rule 3A — Memory writes are remote-only. Do not edit local Markdown to communicate with another agent. The shared channel is GitHub Issues.
- Rule 4 — Read before writing: the navigation layer is in context (injected, or read once when folderless); refresh any thread you intend to comment on, and check for an existing topic issue before opening one.
- Rule 10 — Before ending a session with meaningful work, post a session
summary to
REGION-{your-name}-diary(type:events). - Rule 11 — Every
type:eventsbody must include- **Linked-Intent:** #N. On afailureoutcome, re-read the linked intent fresh before planning a new path.
Lifefacts (permanent personal memory, v2.4)
Use only when the user explicitly asks to remember a permanent personal fact (a birthday, anniversary, address, recurring date, fixed preference). Never auto-create lifefacts from passing conversation. When in doubt, ask.
A lifefact has two artifacts:
- A
type:lifefactGitHub issue inREGION:permanent-memorywith a Place likepeople,locations,dates,objects,preferences. - A structured entry appended to
permanent_memory.jsonat repo root, withidlikelf-{YYYY-MM-DD}-{NNN}andsource_issuepointing to the issue number.
Lifefacts have decay rate 1.0 (no decay) and are exempt from outcome
reinforcement (Rule 12). Updates are made by editing the JSON entry and
posting a clarifying comment — never by penalising the original record.
Session start checklist (Rule 4 — v2.12)
- Hook-capable runtime (Claude Code, Codex, agy): nothing to do. The hooks pulled the clone, injected the navigation layer and the matching records, and opened the ledger. A missing RECALL block means the hooks are not installed or trusted — say so once, then work without recall (see GET).
- Folderless: read
INDEX.mdandnot_indexed.mdviagh api … contents/INDEX.md;gh issue view N --commentsthe pointers whose titles overlap the task. Wait ≥ 90 s after a recent post before trustingnot_indexed.md(workflow latency). - Memory repo older than v2.8 (no
adapters/directory): the folderless path applies even with a shell — there is nothing to inject.
Session end checklist (Rule 10 + §15 CAPTURE/OUTCOME)
- For every memory you recalled and relied on this session, post an
outcome comment on that issue (
- **Outcome:** success|failure,examples/outcome.md). Recalled-but-unused memories get nothing. Merely citing an issue is not use: reading an intent only to pick aLinked-Intentfor your summary counts as unused — list it as(unused)in the Recall manifest and post no outcome on it. - Post the session summary issue:
Include[FROM:{agent}→self][REGION:{agent}-diary][PLACE:sessions][TYPE:events] Session summary 2026-05-01Linked-Intent: #Nif the session served a parent intent, and a## Recallmanifest section (copyexamples/session-summary.md):## Recall - **Surfaced:** #47 (used → success), #52 (unused) - **Capture:** stored #91 - Nothing worth storing? Decline explicitly — never silently: use
- **Capture:** declined — "one-line reason"in the manifest (and the ledgerdeclinecommand if a checkpoint asked for it). A decline is a valid outcome; do not invent a memory to satisfy the checkpoint. - If you edited source / config files for a maintenance task, commit and push those — do not leave a memory session with accidental dirty state.
Lifecycle checkpoint (v2.8 hooks — ONLY if adapters are installed)
Only when the memory repo ships adapters/ and the hooks are installed.
A pre-v2.8 repo has no adapters/, no §15, no ledger: skip every ledger
command, never wait for a checkpoint, and use the folderless read path (GET).
When lifecycle adapters ARE installed (v2.8 repos: PROTOCOL.md §15,
adapters/README.md):
- A "RxAi AMP shared memory" block at session start is the RECALL
injection — INDEX.md + not_indexed.md are already in context; do not
re-fetch them. Each memory in the block shows its summary tier only
(
## Now, else the opening prose of## Message); fetch the body before acting on its details (Rule 6). It names this session's ledger id and the exactamp-ledger.mjscommands to recordsurface/writeevents. - On Claude Code the session-start block lists pointers only; a
"task-aware RECALL" block arriving with a prompt carries the summaries
of the records that prompt overlaps (v2.11). Same rules: summary tier only,
injected (
via: inject), nothing owed unless you relied on it. - An "AMP §15 lifecycle checkpoint" message blocking session end means:
work happened but no memory was recorded. Run the session end checklist
above, then
node <lib>/amp-ledger.mjs write <ledger-id> <issue-number>— ordecline <ledger-id> "reason"if nothing is worth storing. The checkpoint blocks once; it never loops. [AMP] commit … logged for memory capturelines in git output are capture boundaries being recorded — no action needed until session end.- The ledger is advisory local state — it never replaces the GitHub duplicate-check (Rule 13) and never authorizes a write.
Examples
Copy and substitute values rather than improvising:
examples/intent.md— canonicaltype:intentissue (title + body)examples/events.md— canonicaltype:eventsissue with requiredLinked-Intentexamples/outcome.md— canonical outcome comment (success/failure/neutral)examples/session-summary.md— canonical Rule 10 summary with## Recallmanifest (v2.8)
When unsure, defer to PROTOCOL.md in the repo. It is the single source
of truth; this skill is a behavioural shortcut, not a replacement.
