Stores

Stores are typed collections the agent can read and write during sessions. Define store schemas in amodal/stores/*.json; the runtime generates store tools from those files.

amodal/stores/
├── company-profiles.json
└── research-notes.json

Store Definition

{
  "name": "research-notes",
  "entity": {
    "name": "ResearchNote",
    "key": "{company_id}:{topic}",
    "schema": {
      "company_id": { "type": "string" },
      "topic": { "type": "string" },
      "summary": { "type": "string" },
      "confidence": {
        "type": "number",
        "min": 0,
        "max": 1
      },
      "updated_at": { "type": "datetime" },
      "tags": {
        "type": "array",
        "item": { "type": "string" }
      },
      "metadata": {
        "type": "object",
        "fields": {
          "source": { "type": "string" },
          "analyst": { "type": "string", "nullable": true }
        }
      }
    }
  },
  "history": { "versions": 3 },
  "trace": true
}

Field Types

Type	Description	Extra Fields
`string`	Text	`nullable`
`number`	Numeric	`min`, `max`, `nullable`
`boolean`	True or false	`nullable`
`datetime`	ISO 8601 timestamp	`nullable`
`enum`	One of a fixed set	`values`, `nullable`
`array`	List of values	`item`, `nullable`
`object`	Nested object	`fields`, `nullable`
`ref`	Reference to another store	`store`, `nullable`

Generated Tools

For a store named research-notes, the runtime registers namespaced tools:

Tool	Purpose
`store__research_notes__get`	Read one document by key.
`store__research_notes__set`	Create or update one document.
`store__research_notes__query`	Search/filter documents.
`store__research_notes__list`	List documents.
`store__research_notes__remove`	Delete a document.

Kebab-case store names become snake_case in tool names.

Session Type Access

Use session_types in amodal.json to control which stores a session type can use:

{
  "session_types": {
    "research": {
      "stores": {
        "company-profiles": "read",
        "research-notes": "rw"
      }
    }
  }
}

Store access values are "read" for read-only access or "rw" for read/write access.

Storage Backend

In Amodal Cloud, the deployment environment supplies the backing database. Store schemas describe the agent-facing data model; they do not configure Postgres.

For local development, set DATABASE_URL in your environment if you need durable sessions and store data.

Scoped vs. Shared Stores

When scope is configured, store data is partitioned by scope_id by default. Add "shared": true when every scope should read the same collection:

{
  "name": "company-profiles",
  "shared": true,
  "entity": {
    "name": "CompanyProfile",
    "key": "{company_id}",
    "schema": {
      "company_id": { "type": "string" },
      "name": { "type": "string" }
    }
  }
}

Use shared stores for reference catalogs. Use scoped stores for end-user, account, workspace, or tenant-specific data.