Guide agents on effective use of AMFS persistent memory — when to save, what to save, cost-conscious patterns, and session lifecycle. Use when agents interact with AMFS tools, persist knowledge, write memories, read briefings, or commit decision traces.
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).
| 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 |
Every session follows four phases:
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.
Get Briefed — amfs_briefing returns compiled knowledge from the Cortex. One briefing (1 op) replaces many individual reads. Always start here.
Work — read/write/record as you go. Write after meaningful work, not after every edit. Record decisions as they happen, not at the end.
Commit — amfs_commit_outcome snapshots the full decision trace. This is free. Without it, the trace is lost when the session ends.
pattern_refsThe test: "Would a future agent benefit from knowing this, or could they figure it out from the code?"
amfs_briefing gives compiled context in 1 op vs. many individual readsamfs_record_context costs 2 ops; use for meaningful decisions, not micro-stepsamfs_commit_outcome is free and preserves the decision traceUse {repo}/{module} paths. Avoid generic paths like project or code.
myapp/auth, myapp/checkout, myapp/api, acme/infrastructure
| 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) |
| 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 |
| 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.
| 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 |