AWBS: A Filesystem Database Foundation for Agent Workflows

Core Overview of AWBS

AWBS (Agent Work Base Space) is an innovative filesystem database foundation for agent workflows. Its core design includes:

• Uses ordinary filesystems as the main database body, maintaining compatibility with existing toolchains;
• Integrates Git as the version manager, supporting change tracking and rollback;
• Implements isolation via copy-based workspace views;
• Ensures secure write-back through the changeset mechanism.

Original Author/Maintainer: a956180462 Source: GitHub (link) Release Time: 2026-05-23

AWBS aims to solve the pain points of secure workspace management in AI agent workflows, providing agents with a controllable and traceable operating environment.

Challenges in AI Agent Workflows

With the rapid development of LLMs and AI agents, developers need agents to automatically perform tasks like code writing and file modification, but face core issues:

• How to securely manage workspaces to ensure agents only access authorized files?
• How to efficiently track changes and roll back erroneous operations?

Shortcomings of traditional solutions:

• Structured databases are too heavyweight and unsuitable for unstructured files (code, documents);
• Directly operating work directories lacks security boundaries, easily causing risks.

AWBS was born to address these pain points.

Four Core Design Concepts of AWBS

1. Filesystem as Database: Uses standard filesystems as the main database body, no additional import or format conversion required, compatible with existing development toolchains.
2. Git as Version Manager: Deeply integrates Git, uses branches, commits, and history records to implement version control—each agent change is recorded as a Git commit.
3. Copy-based Workspace View: Creates an independent view (identified by UUID) when an agent executes tasks, achieves isolation by copying files to an isolated directory, and generates a sealed authorization contract (specifying read/write paths).
4. Changeset as Write-back Format: Collects changes into a changeset (including context information) after agent modifications; during verification, it checks back against the sealed contract and rejects unauthorized changes.

Multi-Layer Security and Trust Mechanisms

AWBS ensures workflow security through the following mechanisms:

1. Authority Session and Key Escrow: awbs authority session start escrows the key to the background daemon and deletes the local local.json to prevent agents from directly obtaining the key.
2. Controller Token and HMAC Proof: Trusted write commands need to provide a controllerToken, and HMAC verification with nonce prevents replay/man-in-the-middle attacks.
3. Trusted Chain and Audit: awbs ledger bootstrap creates a trusted data chain; awbs db audit can report deviations between the current state and the trusted chain to detect unauthorized modifications.
4. Clean Rebuild Mechanism: awbs db clean-rebuild rebuilds the database from trusted commits, keeping the old directory as a backup to avoid data loss.

Current Features and Application Scenarios

Implemented Features:

• Initialization and Indexing: Supports automatic Git initialization, uses SQLite+FTS5 to build persistent indexes;
• Summary Management: Reads/writes external summaries (no built-in AI model);
• View Lifecycle: Creates, views, and revokes isolated views;
• Changeset Workflow: Collects, checks, and applies changes (only accepts valid changesets based on trusted commits);
• Session Recovery: Uses recoverySecret to recover after abnormal exits.

Application Scenarios:

1. AI-Assisted Development: Agents modify code in isolated spaces; developers review changesets before applying;
2. Automated Workflows: Manages build artifacts and configuration changes in CI/CD;
3. Multi-Agent Collaboration: Works in parallel and merges changes via changesets;
4. Compliance Audit: Change tracing and control in industries like finance/healthcare.

Technical Architecture and Future Planning

Tech Stack: Node.js >=24.0.0, full test coverage (architecture, authority, changeset, etc.).

Unimplemented Features:

• Publish to npm registry;
• OS-level read-only attributes, file ACLs, or strong sandboxes;
• Cross-machine key migration;
• Complete workflow/run/step record layer;
• Automatic deletion of old backups;
• Mode B (independent OS user, system keychain, service-oriented Authority Service).

Conclusion: AWBS brings database capabilities to filesystems. Through Git version control, isolated views, and changeset management, it provides a flexible and secure foundation for AI agent workflows, making it an infrastructure worth attention for AI-assisted development teams.