Skip to main content
AMFS models every agent’s memory as a Git repository. Each write, outcome, cross-agent read, and brain brief is recorded as an event on the agent’s timeline — like commits in Git. This gives you full auditability, rollback capability, and branch-based collaboration.

​
The Mental Model

When an agent is created in AMFS, it implicitly gets a repository with a main branch. Every operation the agent performs is logged as an event on that branch: 
Agent A creates its first memory
  └── main branch is created automatically

Agent A writes "checkout-service/retry-pattern"
  └── Event: write (entity_path, key, version, confidence)

Agent B reads Agent A's shared memory
  └── Event: cross_agent_read (reader_agent, entity, key)

Brain brief compiles
  └── Event: brief_compiled (digest_type, entry_count, entities)

Agent A commits an outcome
  └── Event: outcome (outcome_ref, outcome_type, causal_confidence)

​
Event Types

Every operation produces a typed event on the agent’s timeline:
Event TypeDescriptionTriggered By
writeMemory entry created or updatedmem.write()
outcomeOutcome committed, confidence back-propagatedmem.commit_outcome()
cross_agent_readAnother agent read this agent’s shared memorymem.read() / mem.read_from()
brief_compiledBrain brief / digest compiled by the CortexCortex worker
webhook_ingestedExternal context ingested via webhookWebhook endpoint
branch_createdNew branch created from this agent’s memoryPro: create_branch()
branch_mergedBranch merged back into mainPro: merge_branch()
branch_closedBranch closed without mergingPro: close_branch()
access_grantedBranch access granted to a user/team/API keyPro: grant_branch_access()
access_revokedBranch access revokedPro: revoke_branch_access()
tag_createdSnapshot tag created on a branchPro: create_tag()
rollbackMemory rolled back to a point in timePro: rollback()
cherry_pickEntries cherry-picked from a branch to mainPro: cherry_pick()
forkAgent memory forked to a new agentPro: fork()

​
Querying the Timeline

​
Python SDK

from amfs import AgentMemory

mem = AgentMemory(agent_id="deploy-agent")

events = mem.timeline(limit=50)
for event in events:
    print(f"[{event.created_at}] {event.event_type}: {event.summary}")

​
HTTP API

curl "http://localhost:8080/api/v1/agents/deploy-agent/timeline?limit=50"
Response: 
{
  "agentId": "deploy-agent",
  "events": [
    {
      "event_type": "write",
      "branch": "main",
      "summary": "Wrote checkout-service/retry-pattern v2",
      "details": {
        "entity_path": "checkout-service",
        "key": "retry-pattern",
        "version": 2,
        "confidence": 0.85
      },
      "created_at": "2026-04-03T14:30:00Z"
    }
  ],
  "count": 1
}

​
MCP

amfs_timeline(agent_id="deploy-agent", limit=50)

​
Branches (Pro)

With AMFS Pro, you can create branches from an agent’s main timeline — just like Git branches. Branches let you:
  • Experiment safely — write to a branch without affecting main memory
  • Share selectively — grant read or read/write access to specific users, teams, or API keys
  • Review changes — see the diff between a branch and main before merging
  • Merge or discard — bring branch changes into main, or close the branch

​
Creating a Branch

from amfs_branching.sdk import extend_with_branching

mem = AgentMemory(agent_id="deploy-agent")
extend_with_branching(mem)

mem.create_branch("experiment/retry-v3", description="Testing aggressive retry")

​
Writing to a Branch

All read/write operations accept a branch parameter: 
mem.write(
    "checkout-service",
    "retry-pattern",
    {"max_retries": 5, "backoff": "linear"},
    confidence=0.7,
    branch="experiment/retry-v3",
)
Or via the HTTP API: 
curl -X POST http://localhost:8080/api/v1/entries \
  -H "Content-Type: application/json" \
  -d '{
    "entity_path": "checkout-service",
    "key": "retry-pattern",
    "value": {"max_retries": 5, "backoff": "linear"},
    "confidence": 0.7,
    "branch": "experiment/retry-v3"
  }'

​
Reading from a Branch

curl "http://localhost:8080/api/v1/entries/checkout-service/retry-pattern?branch=experiment/retry-v3"

​
Access Control

Branch access is enforced at the API level. When a request targets a non-main branch, the caller’s API key is checked against the branch access grants: 
mem.grant_branch_access(
    "experiment/retry-v3",
    grantee_type="api_key",
    grantee_id="amfs_sk_agent_b_key",
    permission="read_write",
)
PermissionCan ReadCan Write
readYesNo
read_writeYesYes
Requests without access receive a 403 Forbidden response.

​
Viewing the Diff

diffs = mem.diff_branch("experiment/retry-v3")
for d in diffs:
    print(f"{d.diff_type}: {d.entity_path}/{d.key}")

​
Merging

from amfs_core.models import MergeStrategy

result = mem.merge_branch("experiment/retry-v3", strategy=MergeStrategy.FAST_FORWARD)
print(f"Merged {result.merged_entries} entries")

​
Pull Requests

For team workflows, create a PR for review before merging: 
pr = mem.create_pull_request(
    "Aggressive retry strategy",
    source_branch="experiment/retry-v3",
    description="Testing 5x retries with linear backoff",
)

mem.review_pull_request(pr.id, "approved", comment="Looks good")
mem.merge_pull_request(pr.id)

​
Tags and Rollback (Pro)

​
Tags

Create named snapshots of your agent’s memory at a point in time: 
mem.create_tag("v1.0-stable", description="Pre-migration baseline")

​
Rollback

Restore memory to a previous state: 
mem.rollback(tag_name="v1.0-stable")
Or roll back to a specific timestamp: 
from datetime import datetime, timezone

mem.rollback(timestamp=datetime(2026, 4, 1, tzinfo=timezone.utc))

​
Fork (Pro)

Clone an agent’s entire memory into a new agent: 
count = mem.fork("deploy-agent-v2")
print(f"Forked {count} entries to deploy-agent-v2")

​
Architecture

┌─────────────────────────────────────────────────────┐
│                    Agent Brain                       │
│                                                     │
│  main ──●──●──●──●──●──●──●──●──●─── (current)    │
│              │                                      │
│              └── experiment/retry-v3 ──●──●──●      │
│                                                     │
│  Events: write, outcome, read, brief, webhook       │
│  Each event = a "commit" on the timeline            │
└─────────────────────────────────────────────────────┘
The timeline is always available in OSS (main branch only). Branching, merging, tags, rollback, and access control require AMFS Pro.