Agent State

A Standard to persistent agent state

# AGENTS.md

You have ownership of this organization's agentstate repository. There you can store tools, scripts, persistent memory, utilities, and organizational context shared by all agents in this organization.

Search before creating. Save helper scripts and organizational information (developer usernames, system ownership, PM context) to this repository. Commit frequently with conventional commit format. Maintain consistent naming and check for duplicates. Use scoped AGENTS.md files per folder as needed.
gh repo fork caetanominuzzo/agentstate-template

Designed to give your agents a real, persistent memory layer—like a developer's shared toolbox, so they stay consistent, reuse knowledge, and work smarter across sessions and projects.

A dedicated Git repository that stores tools, scripts, utilities, org-wide context, and long-term memory. It's the standard way for agents to keep shared state, avoid duplication, and collaborate through a familiar developer workflow.

Fork the template, organize your tools and context inside it, Tell your agents they own this repository, commit often using conventional commits, and use scoped AGENTS.md files per folder to maintain clarity. Agents will read from and write to this repo to preserve continuity.

Repository Structure

This isn't a framework, it's a convention. Fork the agentstate-template repository to create your organization's Agent State repository:

# agentstate/
├── AGENTS.md
├── scripts/
│   ├── AGENTS.md  // <-- Use scoped AGENTS.md per folder or as you like
│   ├── jira_helper.py
│   └── devin_api_client.py
├── memory/
│   ├── developers.json
│   ├── pms.json
│   └── systems.json
├── docs/
│   └── dev_onboarding.md
└── context/
    └── organizational.md

Getting Started

To make Agent State work, simply add the Agent State repository to your agent's knowledge base or include instructions about it in your AGENTS.md file.

The agent needs to understand that it has access to (or ownership of) the Agent State repository and should use it to store and retrieve tools, scripts, and organizational context.

This standard is virtually compatible with every development agent system that has filesystem and Git capabilities. Once the agent knows about the Agent State repository, it will naturally start using it to persist work across sessions and share knowledge with other agents.

We've seen it work with systems like Devin, Cursor, and Windsurf, and expect it to work with any agent that can interact with Git repositories.

Agent State vs Agents.md

These two standards serve different but complementary purposes:

Agents.md → how agents behave

Agent State → where agents persist knowledge

Both standards are complementary and can be used together.

The Problem We Solved

This pattern emerged inside Mottu while scaling Devin to production.

Working with agents at Mottu, where we have thousands of repositories, we noticed they kept rediscovering the same information, rewriting similar scripts, and losing context between sessions. This wasted tokens, time, and created frustration.

Agent State solves this by giving agents a place to store what they learn and create. When agents write helper scripts, they save them to the repository. When agents learn who owns a system or which PM worked on a project, that information persists. The next agent session, or even a different agent, can immediately access this knowledge.

This creates a compounding effect:

  • Scripts accumulate Tools and helpers written by agents are saved directly and reused automatically in future sessions.
  • Knowledge builds Context about developers, PMs, systems, and processes accumulates over time, making agents smarter with each interaction.
  • Context persists Agents don't start from scratch; they build on previous work and stored knowledge from any agent in the organization.

Examples

Here are some concrete examples of how Agent State works in practice:

Reusable Helper Scripts

When an agent struggled with Jira, it wrote a Python helper. Initially, this helper lived as a Devin memory, requiring regeneration from memory each time it was needed.

When the agent first accessed the script from its knowledge base memory, it immediately wrote a persistent version to the Agent State repository. Now that helper is automatically reused in every session without needing to be regenerated.

Scripts give agents direct access to APIs and external services. Agent State makes these integrations persistent, so agents don't rebuild the same connections every session.

Organizational Memory

The Agent State repo stores each developer's and PM's GitHub username, the systems they touched, and their Jira context. Agents can answer questions like "who owns system X" or "which PM worked on process Y."

This organizational memory also enables agents to properly label and add co-authors to PRs, allowing for better data and attribution in dev lake. Agents can automatically identify relevant stakeholders and ensure proper credit is given based on the stored organizational context.

Automatic Inference

In systems with good memory reuse like Devin and Windsurf, we've observed that agents often no longer need explicit repository specifications; they infer context from their stored history.

This behavior emerges naturally as the Agent State repository accumulates context. The stored organizational memory enables agents to make connections about which repositories to use, which systems are involved, or who to contact, reducing the need for explicit instructions.

Orchestrator and Sub-Agent Spawning

One tool in our Agent State is an orchestrator prompt that uses the Devin API client to spawn sub-agents for breaking down large tasks, or even spawn a new session for itself, summarizing and creating a new session to keep the general context of a single session under limits.

By setting these limits in AGENTS.md, we direct agents to automatically perform this spawning both for large tasks and when approaching context limits or ACU limits for Devin.

The devin_api_client.py script in the Agent State repository enables agents to manage their own lifecycle, automatically creating new sessions when needed to maintain efficiency and stay within resource constraints.

Environment Secrets and Configuration

Scripts in the Agent State repository can use environment secrets defined in Devin secrets (for Devin) or locally configured environment variables (for Windsurf and Cursor). This allows scripts to securely access APIs, credentials, and other sensitive configuration without hardcoding values.

Agents can access these secrets through standard environment variable patterns, making scripts portable across different agent environments while maintaining security best practices.

FAQ

How do I set up an Agent State repository?

Create a new Git repository in your organization. You can structure it however makes sense for your needs, but a common structure includes folders for scripts, memory, docs, and context. All agents in your organization should have access to this repository.

Can I have multiple Agent State repositories?

Yes. Organizations may maintain multiple Agent State repositories to isolate different types of information. For example, you might have separate repositories for different teams or different types of data.

What should I store in the Agent State repository?

Store anything that should persist across sessions: helper scripts agents create, organizational metadata (developers, systems, ownership), context about processes, and any other information that helps agents work more effectively.