AgentUse: Open-source agent runtime

The store configuration and on-disk item format are experimental and may change without migration. Discuss feedback in GitHub Discussions.

What is the Store?

The store is a local file-based storage system that allows agents to track work items and remember information across multiple runs. It’s particularly useful for:

Multi-run workflows - Track progress when agents run on a schedule
Multi-agent coordination - Share state between agents working together
Task management - Track tasks through status workflows
Agent memory - Remember facts, preferences, and context across runs

Stores live at the AgentUse project root:

<project-root>/.agentuse/store/<store-name>/items.json

When you run agentuse serve -C path/to/agents, -C is the served scope for agent files. AgentUse still walks upward to find the project root, so agent folders inside the same repository can share the same store.

Under agentuse test and any other mock run, every store is re-rooted at <project-root>/.agentuse/store-mock/<timestamp>-<pid>/, seeded on first use by copying the real store so the agent still reads realistic data. Nothing a mock run writes reaches production state, including the reserved metrics store behind the dashboards. The scratch copy is kept so you can inspect what the run would have written, and swept after 7 days.

When you enable the store, your agent automatically gets tools for creating, reading, updating, deleting, and listing items. Tell the agent what to store and when in your agent file’s instructions.

Configuration

Isolated Store

Use store: true for a store that’s private to one agent:

---
model: anthropic:claude-sonnet-5
store: true
---

The store is named after the agent (e.g., myagent from myagent.agentuse).

Shared Store

Use a string name to share a store across multiple agents:

# manager.agentuse
---
type: manager
store: "my-project"
subagents:
  - path: ./writer.agentuse
---

# writer.agentuse
---
store: "my-project"  # Same store as manager
---

All agents using the same store name can read and write to the same data, enabling coordination without explicit communication.

Capabilities

When store is configured, your agent can:

Operation	Description
Create	Add new items with type, title, status, data, and tags
Get	Retrieve a single item by ID (full data, or only selected `fields`)
Update	Modify existing items (merges changes, doesn’t replace)
Conditional update	Compare current status, data fields, or `updatedAt` and update only on a match
Claim	Atomically select and transition one matching item
Delete	Remove items by ID
List	Query and search items with filters, full-text search, and projection

Keep each item compact. Store rows are workflow records, not document or analytics containers. Aim to keep data at or below 8 KiB. Normalize repeated records into separate typed items, and keep large reports or datasets as file artifacts. Larger items are accepted, but store tools warn because reading and updating them consumes substantial model context.

Listing and searching

store_list is built to be token-efficient: by default it returns lightweight summary rows (id, type, title, status, tags, parent, timestamps) without the data payload. The agent scans the summaries, then calls store_get for the full data of the one item it needs, instead of pulling every payload into context. It accepts these parameters:

Parameter	Type	Description
`type`	string	Filter by item type
`status`	string	Filter by status
`parentId`	string	Filter by parent item ID
`tag`	string	Filter by a single tag
`ids`	string[]	Fetch these specific item IDs in one call (batch get)
`where`	object	Exact-match filters on keys inside `data`, e.g. `{ "stage": "review" }`. Numbers and booleans also match their string form (`"5"` matches `5`)
`q`	string	Case-insensitive substring search across title, type, tags, and `data`. Matching summary rows include a short `match` snippet showing where it hit
`includeData`	boolean	Return the full `data` payload of each item (default `false`)
`fields`	string[]	Return only these keys from each item’s `data` (ignored when `includeData` is true)
`since`	string	Only items updated within this window: a relative span (`"7d"`, `"12h"`, `"30m"`), a bare date (`"2026-03-01"`, read as UTC midnight), or a full ISO timestamp
`countOnly`	boolean	Return counts instead of rows (see below)
`limit`	number	Maximum number of items to return
`offset`	number	Number of items to skip (pagination)

The response is { count, total, items }:

count is the number of rows returned and total is how many items match the filters before limit/offset, so the agent knows whether more remain.
Alongside the rows, the response carries a single top-level dataKeysByType map listing the data keys seen for each item type, so the agent knows what it could request via fields or store_get without paying for the key list once per row. On a 243-item store, a 40-row listing went from 6,639 tokens to 3,785 this way. When you pass fields, the key list is dropped entirely and each row instead reports missingFields for any key it doesn’t have.

An unparseable since, or an impossible calendar date like 2026-02-31, comes back as a tool error naming the accepted forms rather than being silently ignored.

Counting

To size a store before reading it, use countOnly: true. It returns total plus byType, byStatus, oldest, and newest, with no rows at all, for around 140 tokens. It respects every filter and ignores limit/offset, so it always describes the whole matching set. This matters because store_list has no default limit: an unfiltered call returns every item and fails loudly against the tool-output cap rather than silently truncating. Ask for the shape first, then ask for rows.

Keep retrieval cheap. Size it (countOnly), narrow it (since, type, status, q), scan the summary rows, then store_get the single item you want. Only set includeData: true (or list fields) when you genuinely need payloads for several items at once. For a known set of IDs, pass ids to fetch them in one store_list call.

The same projection applies to store_get: pass fields: ["url", "score"] to return only those keys from a large item instead of the whole payload.

Atomic coordination

Use store_claim for a shared work queue. Selection and transition happen under one store lock, so two concurrent runs cannot claim the same matching row:

const claim = await tools.store_claim({
  type: "job",
  status: "ready",
  order: "oldest",
  update: {
    status: "in_progress",
    data: { claimedBy: "worker" }
  }
});

An empty queue returns { success: true, claimed: false, item: null }. Use store_update_if for compare-and-set updates. Conditions can include the current status, exact values inside data through where, and the prior updatedAt value. A stale condition returns matched: false without modifying the item. Do not implement claiming as store_list followed by store_update. Another run can select the same item between those calls. Code Mode makes control flow deterministic, but only atomic store primitives make concurrent transitions atomic.

Writing Instructions

Guide your agent’s store usage through clear SOP instructions. Here are common patterns:

State Machine

## Workflow

1. Create items with status "pending"
2. When starting work, update to "in_progress"
3. When complete, update to "done"
4. For failures, update to "failed" with error in data

## Progress Check
- List items with status "pending" to find work
- List items with status "in_progress" to check active work

Parent-Child Relationships

## Structure

- Topic (parent)
  - Article (child linked to topic)
    - Review (child linked to article)

## Finding Related Items
- List articles filtered by parent topic ID
- List reviews filtered by parent article ID

Tagging for Priorities

## Priority Handling

- Tag urgent items with "urgent"
- When checking for work, prioritize items tagged "urgent"
- Use tags like "bug", "feature", "review" for categorization

Agent Memory

## Memory Management

- Store important facts with type "memory"
- Use tags to categorize: "user-preference", "learned-fact", "context"
- Before starting work, list recent memories for relevant context
- When learning something important, store it for future runs

## What to Remember
- User preferences discovered during tasks
- Decisions made and their reasoning
- Facts that will be useful in future runs
- Corrections or feedback received

Storage Location

Stores are saved to:

.agentuse/
  store/
    {storeName}/
      items.json    # The data
      lock          # Process lock file

Don’t edit items.json directly while an agent is running. The lock file prevents corruption from concurrent access.

Example: Content Pipeline

# manager.agentuse
---
type: manager
store: "content"
subagents:
  - path: ./researcher.agentuse
  - path: ./writer.agentuse
---

## SOP

### Research Phase
1. Delegate to researcher to find topics
2. Store each topic with type "topic" and status "pending"

### Writing Phase
1. List pending topics from the store
2. For each topic, delegate to writer with the topic ID
3. Writer creates an article linked to the topic (as parent)
4. Update topic status to "written"

### Status Workflow
- Topics: pending → in_progress → written
- Articles: draft → review → done

Debugging

View Store Contents

If you are running agentuse serve, open the store browser:

http://127.0.0.1:12233/stores

Each store has its own table:

http://127.0.0.1:12233/stores/my-project

Session and approval logs link store tool activity to the matching store table. When AgentUse knows the item ID, the link highlights the changed row:

http://127.0.0.1:12233/stores/my-project?highlight=01KQTG63ZQHFH9PP2B17QWMQZP

# Pretty print store
cat .agentuse/store/my-project/items.json | jq

# Count items by status
cat .agentuse/store/my-project/items.json | jq '.items | group_by(.status) | map({status: .[0].status, count: length})'

Check Lock Status

# See who holds the lock
cat .agentuse/store/my-project/lock

# Remove stale lock (only if agent crashed)
rm .agentuse/store/my-project/lock

Reset Store

# Clear all items (be careful!)
rm -rf .agentuse/store/my-project

Best Practices

Use Meaningful Types

Name your types clearly: “topic”, “article”, “review” instead of “item1”, “item2”.

Define Status Transitions

Document valid status values and transitions in your SOP.

Store Results in Data

Put operation results in the data field for later reference.

Clean Up Old Items

Periodically delete completed items to keep the store manageable.

Next Steps

Manager Agents

Build orchestrating agents with store integration

Scheduling

Run agents on schedules with persistent state

Sub-Agents

Coordinate teams sharing a store

Getting Started

Building

Running

Reference

Store

What is the Store?

Configuration

Isolated Store

Shared Store

Capabilities

Listing and searching

Counting

Atomic coordination

Writing Instructions

State Machine

Parent-Child Relationships

Tagging for Priorities

Agent Memory

Storage Location

Example: Content Pipeline

Debugging

View Store Contents

Check Lock Status

Reset Store

Best Practices

Next Steps

Manager Agents

Scheduling

Sub-Agents

​What is the Store?

​Configuration

​Isolated Store

​Shared Store

​Capabilities

​Listing and searching

​Counting

​Atomic coordination

​Writing Instructions

​State Machine

​Parent-Child Relationships

​Tagging for Priorities

​Agent Memory

​Storage Location

​Example: Content Pipeline

​Debugging

​View Store Contents

​Check Lock Status

​Reset Store

​Best Practices

​Next Steps

Manager Agents

Scheduling

Sub-Agents

What is the Store?

Configuration

Isolated Store

Shared Store

Capabilities

Listing and searching

Counting

Atomic coordination

Writing Instructions

State Machine

Parent-Child Relationships

Tagging for Priorities

Agent Memory

Storage Location

Example: Content Pipeline

Debugging

View Store Contents

Check Lock Status

Reset Store

Best Practices

Next Steps