I saw the next-generation Agent framework at Project89
TechFlow Selected TechFlow Selected
I saw the next-generation Agent framework at Project89
Project89 adopts a completely new approach to designing a high-performance Agent Framework for game development.
Navigating Web3 tides with focused insightsAuthor: 0xhhh
Let me start with the conclusion: @project_89 introduces a completely new approach to designing an Agent Framework—a high-performance framework tailored for game development. Compared to existing Agent Frameworks, it is more modular and offers superior performance.
This article took a long time to write, aiming to help everyone understand how this framework improves upon traditional Agent architectures in terms of design. It went through multiple revisions before reaching its current form. However, some sections remain quite technical, and I couldn't fully simplify them further. If you have any suggestions for improving the article, please leave your comments below.
Developer Background
This is a technical blog post, so let's first look at the founder's technical capabilities:
Prior to project89, the founder worked on this project: https://github.com/Oneirocom/Magick, a software that leverages AI for programming. Shaw is also the fourth-ranked contributor to this project, which is reflected in his resume.
Top-left: Founder of project89; Bottom-right: lalaune (Shaw from ai16z)
Today, we’ll focus on introducing the high-performance Agent Framework within project89:
https://github.com/project-89/argOS
1. Why Use ECS to Design the Agent Framework?
In gaming applications, several major projects already use ECS architecture: blockchain games like MUD and Dojo, and traditional games such as Overwatch and Star Citizen. Moreover, mainstream game engines are gradually shifting toward ECS—Unity being a prime example.
What is ECS?
ECS (Entity-Component-System) is a common architectural pattern used in game development and simulation systems. It strictly separates data from logic, enabling efficient management of numerous entities and their behaviors in large-scale, scalable environments:
-
Entity (实体)
• Just an ID (number or string), containing no data or logic.
• Can be attached with different components to give it various attributes or capabilities. -
Component (组件)
• Stores specific data or state of an entity. -
System (系统)
• Responsible for executing logic related to certain components.
To illustrate this system, consider an example of an Agent performing actions. In ArgOS, each Agent is treated as an Entity and can register different components. For instance, in the image below, this Agent has four components:
- Agent Component: Stores basic information such as Agent name and model name.
- Perception Component: Stores external sensory data perceived by the Agent.
- Memory Component: Stores memory-related data of the Agent Entity, such as past actions.
- Action Component: Stores data about actions to be executed.
Workflow of Systems:
-
If the game detects a weapon in front of the Agent, the Perception System will execute its function to update the corresponding data in the Agent’s Perception Component.
-
Then, the Memory System is triggered, accessing both the Perception and Memory Components to persist the perceived data into the database.
-
Next, the Action System accesses the Memory and Action Components, retrieves environmental context from memory, and executes the appropriate action.
-
Finally, we obtain an updated Agent Entity with all component data refreshed. Thus, Systems define the processing logic applied to specific Components.
Clearly, in project89, the world is filled with various types of Agents. Some Agents not only possess these basic capabilities but also advanced planning abilities. This leads to the structure shown in the following diagram:
System execution flow
However, the actual execution of Systems does not follow a sequential calling pattern—such as Perception System triggering Memory System—as one might expect. There is no direct invocation relationship between Systems. Instead, each System runs periodically—for example:
- Perception System may run every 2 seconds to update incoming sensory inputs and refresh the Perception Component.
- Memory System may run every 1 second, extracting data from the Perception Component and loading it into the Memory Component.
- Plan System may run every 1000 seconds, assessing whether goals need optimization based on received information, then recording updates in the Plan Component.
- Action System may also run every 2 seconds, allowing timely reactions to environmental changes. If the Plan Component is updated, it adjusts the Action Component accordingly, influencing the final action taken.
The above explanation greatly simplifies ArgOS’s architecture to enhance understanding. Now, let’s dive into the real ArgOS.
2. ArgOS System Architecture
To enable deeper thinking and execution of complex tasks, ArgOS includes many Components and Systems.
ArgOS categorizes Systems into three hierarchical levels ("ConsciousnessLevel"):
1) Conscious Systems
- Includes RoomSystem, PerceptionSystem, ExperienceSystem, ThinkingSystem, ActionSystem, CleanupSystem
- High update frequency (e.g., every 10 seconds)
- Closely tied to “real-time” or “conscious-level” processing, such as environmental perception, real-time reasoning, and action execution
2) Subconscious Systems
- Includes GoalPlanningSystem, PlanningSystem
- Lower update frequency (e.g., every 25 seconds)
- Handles “thinking” logic, such as periodic goal evaluation and plan generation
3) Unconscious Systems
- Currently inactive
- Even slower update cycles (e.g., over 50 seconds)
Thus, in ArgOS, Systems are classified by ConsciousnessLevel to determine their execution intervals.
Why design it this way? Because the interdependencies among Systems in ArgOS are extremely complex, as illustrated below:
- PerceptionSystem collects "stimuli" from the environment or other entities and updates them in the Agent’s Perception Component. It determines if stimuli represent significant changes, updating based on stability and processing mode (ACTIVE/REFLECTIVE/WAITING). Ultimately, it provides "current perception" data for downstream systems like ExperienceSystem and ThinkingSystem.
- ExperienceSystem transforms stimuli collected by PerceptionSystem into abstract "experiences." It uses LLMs or rule-based logic (extractExperiences) to identify new experiences and stores them in the Memory Component. It deduplicates, filters, and validates experiences while emitting "experience" events via EventBus for other systems or external listeners.
- ThinkingSystem serves as the Agent’s internal “thought” engine. It extracts current state from Memory, Perception, and other components, generating "ThoughtResults" using generateThought(...) with LLMs or rules. Based on results, it may:
- Update thought history in Memory
- Trigger new Actions (placed in Action.pendingAction[eid])
- Change the Agent’s outward Appearance (e.g., facial expressions, posture), generating associated Stimuli visible to other entities
- ActionSystem checks if Action.pendingAction is non-empty for any Agent. If so, it executes the action via runtime.getActionManager().executeAction(...). After execution, it writes the result to Action.lastActionResult and notifies the room or other entities. It also generates CognitiveStimulus so subsequent systems “know” the action was completed and can incorporate it into memory.
- GoalPlanningSystem periodically evaluates progress on items in Goal.current[eid], or checks for major changes in memory or external conditions (detectSignificantChanges). When new goals are needed or adjustments required, it generates and writes new goals via generateGoals(...). It updates in-progress goals, changing status to complete or failed when conditions are met, and sends corresponding signals to associated Plans.
- PlanningSystem generates or updates Plans for existing goals (Goal.current[eid]). If it detects goals without active plans, it creates a roadmap via generatePlan(...), storing step-by-step instructions in Plan.plans[eid]. It also updates associated Plan statuses upon goal completion/failure and emits relevant cognitive stimuli.
- RoomSystem handles room-related updates:
- Fetches occupant list for the room, generating "appearance" stimuli for each Agent so others can perceive their looks or actions
- Creates environmental stimuli (e.g., ambient “room mood”) and links them appropriately
- Ensures that when an Agent occupies a space, others perceiving that space can detect appearance changes
- CleanupSystem regularly finds and removes entities marked with the Cleanup component. Used to recycle obsolete stimuli or objects, preventing clutter in the ECS.
- Example: A full cycle from “seeing object” to “executing action”
The scenario below illustrates how various Systems collaborate across one or more frames to complete a full loop.
- Setup: An Agent (EID=1) exists in the World, in “Active” state, located in Room (EID=100). A new item, “MagicSword,” appears in the room, generating a corresponding Stimulus.
- PerceptionSystem detects the appearance of “MagicSword” and generates a stimulus (type="item_appearance") added to Perception.currentStimuli[1]. Comparing against the previous stimuli hash, it identifies a “significant change” and reactivates the Agent’s ProcessingState into ACTIVE mode.
- ExperienceSystem notices non-empty Perception.currentStimuli for Agent(1), extracts information like “Sword appears” into one or more new Experiences (type: “observation”), stores them in Memory.experiences[1], and emits an “experience” event.
- ThinkingSystem reads state from Memory and Perception, calls generateThought: “I see the MagicSword—maybe I should pick it up and see what it does…” The resulting Thought contains a pending Action: { tool: "pickUpItem", parameters: { itemName: "MagicSword" } }. ThinkingSystem writes this Action to Action.pendingAction[1]. If there’s an appearance change (e.g., “curious expression”), it updates Appearance and generates visual stimuli.
- ActionSystem sees Action.pendingAction[1] = { tool: "pickUpItem", parameters: ... }, then executes the pickup logic via runtime.getActionManager().executeAction("pickUpItem", 1, { itemName: "MagicSword" }, runtime). Result: { success: true, message: "You picked up the magic sword" }, written to Action.lastActionResult[1], and broadcasts an “action” event to Room(100). It also produces a cognitive stimulus (type="action_result") to be captured by Memory or ThinkingSystem in the next round.
- GoalPlanningSystem (if agent has goals): Periodically assesses agent goals. If one goal is “obtain powerful weapon” and MagicSword is now acquired, marks the goal as complete. If key changes occur (e.g., “new object in room affects goal pursuit?”), uses detectSignificantChanges to create new goals or abandon old ones.
- PlanningSystem (if applicable): For completed or newly generated goals like “obtain powerful weapon,” checks if new Plans are needed or existing ones require updates. If completed, sets associated Plan status to “completed”; if extended workflows emerge (“study magic sword”), generates additional steps.
- RoomSystem (per frame/round): Updates occupant lists and visible entities in Room(100). If Agent(1)'s appearance changes (e.g., Appearance.currentAction = "holding sword"), creates a new “appearance” visual stimulus so Agents 2 and 3 in the same room know “Agent1 picked up the sword.”
- CleanupSystem: Removes entities or stimuli marked for cleanup. If the “MagicSword” Stimulus is no longer needed after pickup, deletes the corresponding Stimulus entity here.
Through these interconnected systems, AI Agents achieve a full cycle: Perception → Experience → Thinking → Action → Goal & Plan Adjustment → Environment Sync → Cleanup.
3. ArgOS Overall Architecture Analysis
1. Core Architectural Layers
2. Component Classification
In ECS, each Entity can have multiple Components. Based on nature and lifecycle, they can be categorized as follows:
- Identity-Level Components
• Agent / PlayerProfile / NPCProfile etc.
• Uniquely identifies the entity, stores core character/unit info, usually persisted to database. - Behavior & State Components
• Action, Goal, Plan, ProcessingState, etc.
• Represents what the entity is currently doing or aiming for, responding to external commands or internal thoughts.
• Includes pendingAction, goalsInProgress, plans, queued thoughts/tasks.
• Typically medium-to-short-term states, dynamically changing per game turn or business cycle.
• Persistence depends on requirements—may be periodically saved to DB for checkpoint/resume functionality. - Perception & Memory Components
• Perception, Memory, Stimulus, Experience, etc.
• Records external sensory input (Stimuli) and abstracted internal experiences.
• Memory often accumulates vast data (dialogue logs, event history), usually requiring persistence.
• Perception may hold real-time/temporary data—only critical perceptions are stored in DB. - Environment & Spatial Components
• Room, OccupiesRoom, Spatial, Environment, Inventory, etc.
• Represents rooms, environments, positions, item containers.
• Fields like Room.id, OccupiesRoom, Environment are often persisted (e.g., room descriptions, map structures).
• Frequently changing components (e.g., movement between rooms) can be synced via events or periodic writes. - Appearance & Interaction Components
• Appearance, UIState, Relationship, etc.
• Tracks externally visible or interactive aspects: avatar, pose, facial expression, social relationships.
• Real-time visuals may stay in memory; key social ties may require persistence. - Auxiliary & Operational Components
• Cleanup, DebugInfo, ProfilingData, etc.
• Marks entities for garbage collection, records debug/profiling data for monitoring.
• Usually exist only in memory unless logging or auditing requires DB sync.
3. System Architecture
Already discussed above.
4. Manager Architecture
Beyond Components and Systems, we also need resource managers—for example, handling database access or resolving state conflicts.
Left: Systems (PerceptionSystem, ExperienceSystem, ThinkingSystem, etc.)
• Each System is scheduled and executed by SimulationRuntime during the ECS loop, querying and processing entities based on component criteria.
• During execution, they interact with Managers:
- Call RoomManager (RM) to query/update room info
- Use StateManager (SM) to get/save world/agent states (Memory, Goal, Plan, etc.)
- Leverage EventBus (EB) to broadcast/listen to events
- Invoke PromptManager (PM) when NLP or prompt templating is needed
----------------
Right: Managers (EventBus, RoomManager, StateManager, EventManager, ActionManager, PromptManager, etc.)
• Provide system-level services, rarely driving logic directly, instead called by Systems or Runtime.
• Examples:
- ActionManager: Manages registration and execution of Actions
- EventManager / EventBus: Handles publish-subscribe event mechanism
- RoomManager: Manages rooms, layout, occupants
- StateManager: Synchronizes ECS with databases/storage
- PromptManager: Provides LLM prompt templates and context management
Middle: SimulationRuntime (R)
• Acts as the “scheduler” for all Systems, starting/stopping loops across different levels (Conscious/Subconscious, etc.).
• Creates Managers during initialization and injects them into Systems.
- CleanupSystem: Also interacts with ComponentSync (CS) to ensure component/event subscriptions are removed when entities are recycled.
Conclusion: Each System accesses data or services via corresponding Managers when needed, while Runtime orchestrates the lifecycle and behavior of all Systems and Managers at a higher level.
5. How Vector and Database Interactions Work
In ECS, Systems execute logic, while database reads/writes are handled by a dedicated “PersistenceManager / DatabaseManager” or “StateManager.” The general workflow is as follows:
- Initial Load (Startup/Initialization)
• StateManager / PersistenceManager loads core persistent data (Agents, Rooms, Goals, etc.) from the database.
• Creates corresponding Entities and initializes their Components.
• Example: Read agent records from DB and instantiate Agents with Agent, Memory, Goal components. - Runtime Execution (System Update Loop)
• Systems operate each frame/turn:
- PerceptionSystem collects sensory input and writes to Perception Component (often temporary, not persisted)
- ExperienceSystem converts stimuli into Experiences, writing to Memory.experiences; critical ones may trigger immediate persistence or mark needsPersistence flag for batch write later
- ThinkingSystem / ActionSystem / GoalPlanningSystem make decisions and update ECS fields
• Major changes (e.g., new long-term goal in Goal.current) trigger StateManager to persist via event/component listener
- Periodic or Event-Driven Persistence
• At key points (e.g., plan update, major event), call PersistenceManager.storeComponentData(eid, "Goal") to persist.
• Or, in CleanupSystem or timer jobs, let StateManager scan entities with needsPersistence flag and batch-write to DB.
• Logs or audit trails (e.g., action history, thought logs) can also be archived here. - Shutdown or Checkpoint Save
• On server shutdown, call StateManager.saveAll() to flush remaining data to DB, ensuring ECS state recovery on restart.
• In offline/single-player scenarios, manual save triggers are supported.
- Complete Example Flow
Demonstrates possible interaction patterns between components and the database:
- Startup: StateManager.queryDB("SELECT * FROM agents") → gets agent records, creates Entity (EID=x) for each, initializes Agent, Memory, Goal components. Loads room data from “rooms” table and creates Room entities.
- Runtime: PerceptionSystem detects “MagicSword appeared” in a room, writes to Perception.currentStimuli[eid]. ExperienceSystem converts Stimuli into Experience, assigns to Memory.experiences[eid]. ThinkingSystem uses Memory, Goal to decide next action, generates Action.pendingAction[eid]. ActionSystem executes action, writes result to Memory or Action.lastActionResult. If a major plot event occurs, marks latest Memory.experiences[eid] with needsPersistence. Later, StateManager detects needsPersistence flag and persists to DB (INSERT INTO memory_experiences...).
- Shutdown/Checkpoint: On server shutdown, invoke StateManager.saveAll(), saving latest state of key components (Agent, Memory, Goal, etc.) to DB. Upon restart, reload and restore full ECS world state.
- Component classification helps manage data clearly and define boundaries between ephemeral (in-memory) and persistent data.
- Database interactions are centralized via a dedicated Manager (e.g., StateManager), avoiding direct SQL or low-level code inside Systems.
- This combines ECS’s efficiency and flexibility in logic with the benefits of database persistence, checkpoint/resume capability, and analytics.
5. Architectural Innovations
- The key innovation lies in the independence of each System—no direct invocation between Systems. Even though functionalities like “Perception → Experience → Thinking → Action → Goal Planning → Environment Sync → Cleanup” involve interdependencies, the ECS architecture decouples them into independent, standalone Systems. This modularity ensures zero coupling. I believe this is precisely why Unity has been increasingly migrating toward ECS in recent years.
- Additionally, if you want an Agent with only basic capabilities, you simply reduce the number of registered Components and Systems during Entity definition—requiring little to no code changes.
As shown in the figure:
- If you wish to add new features during development, you can easily plug them in without affecting other Systems. Furthermore, this architecture significantly outperforms traditional object-oriented designs—a well-established fact in the gaming industry. ECS is inherently more concurrency-friendly, offering substantial advantages in complex DeFi scenarios. In particular, for Agent-based quantitative trading, ECS could prove highly effective—not just limited to gaming contexts.
- Classifying Systems into conscious, subconscious, and unconscious levels to regulate execution frequency is an exceptionally clever design—it closely mirrors human cognitive processes.
In my opinion, this is an extremely modular, high-performance framework with excellent code quality and comprehensive documentation. Unfortunately, the $project89 project has lacked promotion for this framework, which is why I spent considerable time (four days) writing this article. Truly good innovations deserve recognition. I plan to release an English version tomorrow, hoping more game teams or DeFi teams will discover this framework and consider it as a viable architectural alternative!
Join TechFlow official community to stay tuned
Telegram:https://t.me/TechFlowDaily
X (Twitter):https://x.com/TechFlowPost
X (Twitter) EN:https://x.com/BlockFlow_News
@hhh69251498
