amfs-memory

AMFS Memory — Agent Behavioral Rules

You have access to AMFS (Agent Memory File System) through MCP tools. AMFS gives you a persistent brain — memory that survives across sessions, agents, and machines. Use it to build institutional knowledge over time.

MANDATORY FIRST STEP: Set Your Identity

You MUST call amfs_set_identity before doing anything else. Without it, all your work is attributed to a generic default and you won't appear as a distinct agent on the AMFS dashboard.

amfs_set_identity("<role-name>", "<one-line description of current task>", model="<your-model-name>")

Always pass model= with your LLM model name (e.g. "claude-4-opus", "gpt-4o", "claude-3.5-sonnet"). This is recorded in decision traces so we know which model made each decision.

Sticky identity: Once set, the identity is saved to ~/.amfs/.identity and automatically restored in future sessions — even across process restarts (e.g. Claude Desktop). You only need to call amfs_set_identity again to change roles or update the description.

Use amfs_whoami() to check the active identity. Use amfs_reset_identity() to clear it.

Naming rules:

• Use kebab-case role/domain names that persist across conversations about the same topic.
• Good: "dashboard-agent", "stripe-agent", "api-agent", "infra-agent", "mcp-agent"
• Bad: "fix-button-color" (too specific — won't be reused), "agent-1" (meaningless)
• If you're continuing work a previous agent started, use the same name to build on their knowledge.
• The description should say what you're doing right now (e.g. "Fixing tag rollback for slashed names").

When to GET BRIEFED (start every session with context)

• Before starting any work: Get a compiled briefing from the Memory Cortex. This gives you pre-compiled knowledge about the entities you're about to work on — what other agents know, recent risks, external events, and confidence-ranked facts. This is your most important first step.

  amfs_briefing(entity_path="<repo>/<module>")
  

• Read the evidence sections first. The lead digest carries validated (entries every outcome confirmed — act on these), discredited (entries a failure gated, with replaced_by where known — avoid these) and regime_shift (long-validated entries that recently started failing — something changed; verify before reusing anything in the scope). Each hot_context row has an evidence_status: untested, validated, contested or discredited. compact=True returns just the lead digest with these sections.
• The briefing also carries tried_here (actions taken on this entity and how each fared) and, under a regime shift, an explore line with the untried action assigned to you. Pass since=<iso timestamp> on a repeat call to get only what changed.
• Then recall your own specific memories and search for details:

  amfs_recall("<repo>/<module>", "<relevant-key>")
  amfs_search(entity_path="<repo>/<service-or-module>")
  

• Before choosing among a fixed set of actions (a tool with an enum action, a runbook with numbered fixes): retrieve with the candidates and follow the recommendation.

  amfs_retrieve(query="<the task>", entity_path="<repo>/<module>", include_priors=True,
                candidate_actions=["resolve:resend_email", "resolve:update_payment_method"], compact=True)
  

  action_priors lists each action's won/lost here on similar tasks; recommendation.mode is act (take suggested_action), explore (everything tried here failed or a regime shift is flagged — try suggested_action first; it is assigned per agent so peers explore different actions), or escalate (every candidate has been tried and failed — escalate on the first attempt). compact=True keeps the first two hits full and the rest as one-liners; priors and recommendation are always complete.
• Before making architectural decisions: Get a briefing first, then check specific patterns.

  amfs_briefing(entity_path="<repo>/<module>")
  amfs_search(query="<topic>", min_confidence=0.5)
  

• When encountering errors: Check if the Cortex or another agent already has context.

  amfs_briefing(entity_path="<repo>/<module>")
  amfs_search(query="<error-keyword>")