# Raia Live Amfs Amfs > AMFS Agent Memory Guide - Skill: `tomevault-io/raia-live-amfs-amfs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/raia-live-amfs-amfs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/raia-live-amfs-amfs/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/raia-live-amfs-amfs --- # AMFS Agent Memory Guide Persistent memory that survives across sessions, agents, and machines. This guide covers decision rules and conventions — not tool syntax (the MCP server already provides that). ## Cost Model | Operation | Cost | Examples | |:----------|:----:|:--------| | Read | 1 op | `amfs_read`, `amfs_search`, `amfs_list`, `amfs_recall`, `amfs_briefing`, `amfs_retrieve` | | Write | 2 ops | `amfs_write`, `amfs_record_context` | | Commit | FREE | `amfs_commit_outcome` — always commit, never skip | ## Session Lifecycle Every session follows four phases: 1. **Identify** — `amfs_set_identity` with a stable kebab-case role name (e.g. `api-agent`, `infra-agent`). Reuse the same name across conversations about the same domain. Don't use task-specific names like `fix-button-color`. 2. **Get Briefed** — `amfs_briefing` returns compiled knowledge from the Cortex. One briefing (1 op) replaces many individual reads. Always start here. 3. **Work** — read/write/record as you go. Write after meaningful work, not after every edit. Record decisions as they happen, not at the end. 4. **Commit** — `amfs_commit_outcome` snapshots the full decision trace. This is free. Without it, the trace is lost when the session ends. ## What to Save (worth 2 ops) - **Decisions with rationale** — why X over Y, trade-offs considered - **Discovered patterns** — reusable across sessions, link with `pattern_refs` - **Risks and bugs** — gotchas that would trip up future agents - **Task summaries** — what was done and key outcomes after significant work - **External tool outputs** — API results, metrics, incident data that informed decisions ## What NOT to Save - **Trivial edits** — "renamed variable", "added comment" — VCS tracks these - **File-level changes** — save the *decision*, not the diff - **Recomputable info** — anything derivable from the codebase in under 5 seconds - **Transient debug output** — stack traces, test logs - **One-sentence entries** — too low signal for 2 ops; batch into richer entries **The test:** "Would a future agent benefit from knowing this, or could they figure it out from the code?" ## Cost-Conscious Patterns - **Briefing first** — `amfs_briefing` gives compiled context in 1 op vs. many individual reads - **Batch writes** — one rich entry beats three thin ones (2 ops vs. 6 ops) - **Search before writing** — avoid duplicating existing entries - **Record context selectively** — `amfs_record_context` costs 2 ops; use for meaningful decisions, not micro-steps - **Always commit** — `amfs_commit_outcome` is free and preserves the decision trace ## Entity Paths Use `{repo}/{module}` paths. Avoid generic paths like `project` or `code`. ``` myapp/auth, myapp/checkout, myapp/api, acme/infrastructure ``` ## Key Prefixes | Prefix | Use case | |:-------|:---------| | `pattern-` | Reusable patterns | | `risk-` | Known risks or bugs | | `decision-` | Architectural decisions | | `task-summary-` | What was done and why | | `action-` | Actions taken (experience log) | ## Memory Types | Type | Use when | Decay | |:-----|:---------|:------| | `fact` (default) | Stable knowledge — patterns, configs, verified decisions | Normal | | `belief` | Hypotheses, unverified observations (confidence < 0.9) | 2x faster | | `experience` | Actions taken, deployment logs | 1.5x slower | ## Confidence Scale | Score | Meaning | |:------|:--------| | 1.0 | Verified fact, tested in production | | 0.7–0.9 | High confidence, not yet production-tested | | 0.4–0.6 | Hypothesis, needs validation | | < 0.4 | Speculative, early signal | Beliefs should always be < 0.9. If you're sure enough for 0.9+, it's a fact. ## Anti-Patterns | Don't | Do instead | |:------|:-----------| | Write every file edit | Write the *decision*, not the change | | Forget `amfs_commit_outcome` | Always commit — it's free | | Use generic entity paths | Use `{repo}/{module}` | | Set confidence=1.0 on beliefs | Beliefs are hypotheses — keep < 0.9 | | Skip `amfs_briefing` | One briefing replaces many reads | | Write one-sentence entries | Batch into richer entries | | Record every micro-step | Record meaningful decisions only | --- > Source: [raia-live/amfs](https://github.com/raia-live/amfs) — distributed by [TomeVault](https://tomevault.io).