AgentUse - Autonomous Agents That Work Without You

Experimental Feature: The Store is experimental. The configuration and data format may change or be removed in future versions. 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.

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)
Delete	Remove items by ID
List	Query and search items with filters, full-text search, and projection

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)
`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.
Each summary row (when data is omitted) includes a dataKeys array listing the keys available in that item’s data, so the agent knows what it could request via fields or store_get without seeing the values.

To get counts by status or type, filter and read total (e.g. store_list({ status: "pending" })) rather than scanning rows.

Keep retrieval cheap. Narrow with filters or q first, 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.

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

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

​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

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