raia-live/amfs/cursor

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

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.

1. Get Briefed — amfs_briefing returns compiled knowledge from the Cortex. One briefing (1 op) replaces many individual reads. Always start here.

1. Work — read/write/record as you go. Write after meaningful work, not after every edit. Record decisions as they happen, not at the end.

1. 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

Memory Types

Confidence Scale

Beliefs should always be < 0.9. If you're sure enough for 0.9+, it's a fact.

Anti-Patterns