Agent State

A Standard for 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. A standard way for agents to keep shared state, avoid duplication, and collaborate through a familiar developer workflow.

Fork the template and 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.

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 and 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

These are from our actual use at Mottu, not hypotheticals:

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

When an agent has access to hundreds or thousands of repositories, users typically need to specify which one to work on for each task. With Agent State, the agent loads the user's profile from organizational memory, sees which repositories this user has worked on recently and what each one does, and matches the new task to the right repo on its own.

This works when the organizational memory is well-maintained and the task description is clear enough to match against stored context. It's not magic—it's the agent reasoning over structured data instead of starting blind.

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. For Keycloak/OIDC environments, sso-cli lets agents fetch auth tokens on demand without storing credentials.

Limitations & Considerations

This pattern emerged from real production use. Here's what we've learned about its rough edges.

Cross-Repository Access

For local agents like Cursor, Windsurf, or Claude Code to use the Agent State repo, developers need write access to it. But any user with access to the agent system gets indirect access to all repositories configured on that agent's machine.

This is the same limitation as Devin's team plan, where all team members with Devin access share indirect access to every repository configured in Devin's environment.

Scope access carefully. Consider who can instruct the agent and what repositories are reachable from that agent's environment. Treat agent access as a shared credential.

Concurrent Write Conflicts

Multiple agents writing to the same Agent State repo simultaneously can cause Git merge conflicts. Git handles some of this naturally, but at scale—many agents, frequent commits—conflicts require operational attention.

Strategies include using branches per agent or per session, accepting that some manual conflict resolution will be needed, or partitioning the repo by team.

State Quality and Drift

There is no validation layer. Agents can write incorrect, outdated, or contradictory information to the repo. Over time, state can drift from reality—outdated developer mappings, deprecated scripts that still get referenced, conflicting context across files.

Treat the Agent State repo like shared documentation: review it periodically, prune what's stale, and correct what's wrong. This is maintenance work that doesn't go away.

No Fine-Grained Access Control

The repo is all-or-nothing. There's no built-in way to restrict which agents or users can see specific files within the Agent State repo. Organizational data—developer names, system ownership, PM context—is visible to anyone with repo access.

For teams needing isolation between groups or projects, maintain multiple Agent State repositories with different access scopes rather than trying to restrict within a single repo.

Context Window Pressure

As the Agent State repo grows, agents may struggle to effectively use all of it within their context window. A large, disorganized repo can actually hurt performance by overwhelming the agent with too much information, leading to worse results than having no shared state at all.

Keep the repo well-organized and actively pruned. Use scoped AGENTS.md files to guide agents to relevant sections. Bigger is not always better—curate ruthlessly.

Script Security

Scripts stored in the Agent State repo run with the agent's full permissions. A buggy or poorly written script can cause damage across repositories—deleting branches, pushing broken code, or leaking secrets through API calls.

Extend code review practices to the Agent State repo, especially for scripts that interact with external services or modify other repositories. Agent-authored code deserves the same scrutiny as human-authored code.

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

Add instructions about the Agent State repository to your AGENTS.md file, or include it in your agent's knowledge base. The agent needs to know it has access to (or ownership of) this repository and should use it to store and retrieve tools, scripts, and organizational context.

This works with any agent system that has filesystem and Git access. Once you tell the agent about the Agent State repository through its instructions, it will start using it to persist work across sessions and share knowledge with other agents.

We've seen it work with Devin, Cursor, Windsurf, Claude Code, Antigravity, and Copilot. It should 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

In practice, your AGENTS.md file is where you tell agents about the Agent State repo.

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.