AFS Agentic Workflow Architecture

Version: 0.1.0
Last Updated: 2026-02-14
Status: Production Ready

Executive Summary

AFS (Agent File System) is a CLI-first, filesystem-first agent memory system that serves as the memory substrate for modern AI agent workflows. It uniquely bridges the gap between:

• Anthropic’s Agent Teams (coordinator-executor pattern)
• Kimi’s Agent Swarms (commander-cluster parallel pattern)

By providing persistent, shareable, graph-enabled memory infrastructure, AFS enables both deep reasoning workflows and massive parallel agent execution.

Key Value Proposition

AFS doesn’t replace agent orchestration frameworks—it enables them to scale by solving the hard problem of agent memory persistence and sharing.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         AFS LAYER                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Memory     │  │   Graph      │  │   Swarm      │              │
│  │   Engine     │  │   Store      │  │   Manager    │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
│         ↓                 ↓                 ↓                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │              Unified CLI (`afs`) - Namespaces                │   │
│  │  memory | query | graph | agent | admin | maintenance         │   │
│  │  session | scheduler | attachment | models                   │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                     AGENT WORKFLOW LAYERS                           │
│                                                                     │
│  ┌─────────────────┐     ┌─────────────────┐     ┌───────────────┐ │
│  │ ANTHROPIC TEAMS │     │   AFS SWARM     │     │ KIMI SWARMS   │ │
│  │  (Coordinator-  │  ←→ │  (Memory Layer) │  ←→ │ (Commander-   │ │
│  │   Executor)     │     │                 │     │   Cluster)    │ │
│  └─────────────────┘     └─────────────────┘     └───────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Core Components

Industry Pattern Coverage

AFS implements patterns found in leading agent frameworks:

Quick Start

Installation

# Install from source
pip install -e .

# Or with optional embeddings
pip install -e ".[embeddings]"

Basic Usage

# Create a memory
afs memory create --agent-id myagent --content "Hello world" --type observation

# Search memories
afs query search --agent-id myagent --query "hello"

# Join a swarm
afs agent join --agent-id myagent --swarm-id team-1

# Share knowledge
afs memory share --agent-id myagent --swarm-id team-1 --memory-id <id>

Documentation Structure

This documentation is organized into the following sections:

1. Workflow Patterns - Detailed patterns for different agent architectures
2. CLI Reference - Complete command reference
3. Integration Guide - Using AFS with CrewAI, AutoGen, LangGraph
4. Daily Operations - Common daily workflows

Key Concepts

Memory Tiers

AFS implements a three-tier memory system inspired by human cognition:

Memory Lifecycle

encoding → retrieval → consolidation → reconsolidation → extinction
   ↓          ↓            ↓                ↓              ↓
 create    access    group & synthesize   update      delete

Graph Relationships

Memories are connected via typed edges:

• similar_to - Semantic similarity (cosine similarity >= threshold)
• co_occurred - Temporal proximity (within time window)
• consolidated_from - Knowledge synthesis (created from group)
• depends_on - Task dependency (workflow tracking)

Performance Characteristics

Audit Logging

All AFS engine operations are automatically audit-logged. Agents don’t need to do anything special — the logging happens inside the engine and covers every operation category:

• Memory: create, retrieve, search, forget, consolidate, recall, reflect, inspect, stats
• Graph: mine, add edge, query edges, shortest path, export
• Session: create, get, update, delete, list, activate, deactivate
• Swarm: share, cancel, status
• Scheduler: start, stop, status
• Attachment: upload, get, list, delete

Fail-Open Guarantee

If audit logging fails, the memory operation still succeeds. Audit infrastructure issues never block agents.

Querying the Audit Trail

# CLI
afs admin audit --agent-id my-agent --limit 20

# Filter by status to find errors
afs admin audit --agent-id my-agent --status error

# API
GET /admin/audit?agent_id=my-agent&limit=20

Common uses in agentic workflows:

For the full operation taxonomy and payload field conventions, see src/afs/audit_taxonomy.py or docs/cli-reference.md.

When to Use AFS

✅ Ideal For

• Multi-agent systems requiring shared knowledge
• Workflows with sequential and parallel phases
• Teams needing audit trails and compliance
• Long-running agents with memory lifecycle needs
• Offline-first or air-gapped environments

❌ Not Ideal For

• Simple single-agent applications (overkill)
• Real-time collaborative editing (use CRDTs)
• Heavy write-heavy workloads (optimistic locking)
• Need for sub-millisecond latency (filesystem overhead)

Next Steps

1. Read Workflow Patterns to understand how AFS fits your architecture
2. Review CLI Reference for command details
3. Follow Integration Guide to connect with your framework
4. See Daily Operations for common tasks

Support & Resources

• Repository: /Users/kinshingwong/Documents/GitHub/labs21/project-afs
• CLI Entry: afs --help
• API Server: afs-server (default port 8080)
• Configuration: .afs/config.yaml (MEMSYS env vars ignored)

For detailed implementation examples and code patterns, see the individual documentation files linked above.