> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt > Use this file to discover all available pages before exploring further. # Store > Persistent data storage for tracking work items across agent runs **Experimental Feature**: The Store is experimental. The configuration and data format may change or be removed in future versions. Discuss feedback in [GitHub Discussions](https://github.com/agentuse/agentuse/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: ```text theme={"system"} /.agentuse/store//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: ```yaml theme={"system"} --- 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: ```yaml theme={"system"} # 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 ```markdown theme={"system"} ## 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 ```markdown theme={"system"} ## 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 ```markdown theme={"system"} ## 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 ```markdown theme={"system"} ## 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 ```yaml theme={"system"} # 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: ```bash theme={"system"} http://127.0.0.1:12233/stores ``` Each store has its own table: ```bash theme={"system"} 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: ```bash theme={"system"} http://127.0.0.1:12233/stores/my-project?highlight=01KQTG63ZQHFH9PP2B17QWMQZP ``` ```bash theme={"system"} # 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 ```bash theme={"system"} # 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 ```bash theme={"system"} # Clear all items (be careful!) rm -rf .agentuse/store/my-project ``` ## Best Practices Name your types clearly: "topic", "article", "review" instead of "item1", "item2". Document valid status values and transitions in your SOP. Put operation results in the `data` field for later reference. Periodically delete completed items to keep the store manageable. ## Next Steps Build orchestrating agents with store integration Run agents on schedules with persistent state Coordinate teams sharing a store