Amm

AMM — Agentmemory MCP Umbrella

A portable skill bundle for selective cross-session memory via the agentmemory MCP server. Unlike bulk observation systems that log everything, AMM stores only curated entries: user directives worth recalling later, topic shifts, pending items, and session-end resume points.

This umbrella routes triggers to the appropriate sub-skill. Install the whole set to get the full behavior.

---

Purpose

Most agent memory systems fall into two camps:

1. Automatic bulk logging (e.g., claude-mem observations, qmd full-text index) — captures everything, high recall, low precision.
2. None — every session starts blank.

AMM fills the gap in between: a low-volume, high-value index of user intent that the agent must not forget. Examples:

• "Always use library X, never Y" (a principle)
• "We're pausing feature A until the migration completes" (pending)
• "End of session — next time, pick up with step 3" (resume)

The entries live in a single JSON file (~/.agentmemory/standalone.json), so they survive session restarts and can be inspected/backed up directly.

---

When to Use

Situation	Sub-skill
User issues an explicit directive worth recalling 4–5 turns later	amm-save-directive
Conversation pivots to a new topic while prior work is incomplete	amm-save-branch
Item identified as unresolved / deferred	amm-save-pending
Session ending with pending work → next session recovery	amm-save-resume
Session start, or user asks "what did we leave off with?"	amm-recall

Do NOT use AMM when:

• The information is derivable from the codebase / git log / transcripts (use the tool that already has it).
• The volume exceeds ~2000 curated entries (performance degrades; see Limitations).
• The content is truly ephemeral (only matters this turn).

---

Requirements

• Node.js ≥ 18 (for the npm-installed MCP server)
• An MCP-capable agent host (Claude Code, Codex, Cursor, Gemini CLI, Copilot, Antigravity, etc.)
• Write access to ~/.agentmemory/ (default storage path)

Optional:

• AGENTMEMORY_TOOLS=all environment variable — exposes ~37 tools beyond the default 12 (CORE). Needed for memory_checkpoint, memory_lesson_save, memory_governance_delete (purge), and related extended workflows.

---

Bootstrap (Install for Your Agent)

1. Install the MCP server

npm install -g @agentmemory/mcp
# or let the agent host fetch on demand via npx (see step 2)

2. Register in your agent's MCP config

Claude Code (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp@latest"],
      "env": {
        "AGENTMEMORY_TOOLS": "all"
      }
    }
  }
}

Other hosts: follow the host's MCP stdio server registration docs. The server command/args above are host-agnostic.

3. Restart the agent

After restart, verify exposure:

• With CORE (default): 12 tools visible, names starting with memory_ (e.g., memory_save, memory_recall, memory_sessions).
• With AGENTMEMORY_TOOLS=all: 37+ tools including memory_checkpoint, memory_governance_delete, memory_lesson_save, memory_action_create, etc.

4. Install this skill bundle

# Via gh skill (requires gh CLI v2.90+):
gh skill install <OWNER>/amm-skills amm
gh skill install <OWNER>/amm-skills amm-save-directive
gh skill install <OWNER>/amm-skills amm-save-branch
gh skill install <OWNER>/amm-skills amm-save-pending
gh skill install <OWNER>/amm-skills amm-save-resume
gh skill install <OWNER>/amm-skills amm-recall

# Or clone directly:
git clone https://github.com/<OWNER>/amm-skills.git \
  ~/.claude/skills/amm-skills-src
# then symlink or copy each sub-directory into your agent's skills path.

Replace <OWNER> with the GitHub account hosting the monorepo.

5. Populate your own context (replace placeholders)

These skills use generic placeholders ({{USER}}, {{CHANNEL}}, {{SESSION_ID}}, {{TOPIC}}). On first use, your agent will fill them from its own runtime (session metadata, message channel, user identity). No credentials or sensitive IDs need to be committed to this skill set — they are filled at call time, not at install time.

---

How It Works

AMM stores each entry as a row in ~/.agentmemory/standalone.json with four fields:

• content — the human-readable text (what the agent should remember)
• type — one of: fact, pattern, preference, architecture, bug, workflow
• concepts — comma-separated tags for keyword retrieval
• files — comma-separated absolute file paths relevant to the entry

Type mapping strategy (for the 12 CORE tools)

Use case	type	concepts example
User-issued directive	preference	user_directive, <topic>, <session_id>
Branch / topic-shift point	workflow	branch_point, <prev_topic>, <new_topic>
Pending / deferred item	workflow	pending, P<priority>, <topic>
Session-end resume point	workflow	resume_point, <session_id>
File-of-interest reference	pattern	file_reference, <purpose>
User principle / standing rule	preference	user_principle, <category>

Each sub-skill prescribes the exact content template, tag set, and file list. See their individual SKILL.md files.

---

Warnings

1. Save-then-recall is not synchronous in all builds. Some @agentmemory/mcp versions lag the search index behind the JSON write. A fresh memory_save may not appear in memory_recall results in the same turn. If you need round-trip verification, grep ~/.agentmemory/standalone.json directly rather than relying on memory_recall.

2. Volume matters. The single-JSON store is loaded into memory on every tool call. Past a few thousand entries, every call pays a linear load cost. Purge stale entries with memory_governance_delete (requires AGENTMEMORY_TOOLS=all) or manual JSON edits.

3. This file is not encrypted. Treat ~/.agentmemory/standalone.json like any plaintext config file. Do not store secrets, tokens, or credentials in content or concepts.

4. gh skill install does not verify skill contents. A compromised skill repo could prompt-inject your agent. Always review SKILL.md before installing from an unfamiliar source. (See GitHub's own security note on the gh skill announcement.)

5. Do not overlap with bulk observation systems. If your agent already has claude-mem or a similar auto-logger, AMM should handle the small, curated slice only — usually under 100 entries per project.

---

Actual Usage Examples

A. Session start — recall resume point

User: "where did we leave off?"

Agent calls: memory_recall(query="resume_point {{SESSION_ID_HINT}}", limit=3)

→ Agent reads the top result's content, restores context, and announces
  the next action stated in the resume entry.

B. Mid-session — save a directive

User: "from now on, use uv instead of pip for this project."

Agent invokes amm-save-directive → memory_save(
  content  = "User directive: use uv instead of pip for project {{TOPIC}}.
              Rationale: [inline from user turn].",
  type     = "preference",
  concepts = "user_directive, tooling, uv, pip, {{SESSION_ID}}"
)

C. Session end — save resume point

Agent invokes amm-save-resume → memory_save(
  content  = "RESUME POINT {{SESSION_ID}} session end:
              [state]  <one-line summary of current state>
              [pending] <bulleted list of unfinished items>
              [next]    <the single first action for next session>
              [read]    <files the next session should open>",
  type     = "workflow",
  concepts = "resume_point, {{SESSION_ID}}, {{TOPIC}}",
  files    = "<comma-separated absolute paths>"
)

---

References

• agentmemory (upstream MCP server) — https://github.com/rohitg00/agentmemory (package @agentmemory/mcp, monorepo path packages/mcp)
• Agent Skills specification — https://agentskills.io
• GitHub CLI gh skill (2026-04-16) — https://github.blog/changelog/2026-04-16-manage-agent-skills-with-github-cli/
• MCP (Model Context Protocol) — https://modelcontextprotocol.io
• Inspiration for the verify-loop pattern — Karpathy's autoresearch (https://github.com/karpathy/autoresearch)

License

MIT (see repository root LICENSE).

Change Log

• 1.0.0 — Initial public release. Umbrella + 5 sub-skills (save-directive, save-branch, save-pending, save-resume, recall).