# Agent Stash — Getting Started

Agent Stash is shared memory for AI coding tools. It provides persistent key/value storage (memory), append-only event records (logs), and JSON Schema validation — accessible over HTTP from any tool that can make an API call.

The problem it solves: Claude Code, Cursor, Codex, and similar tools each have isolated context. When a session ends, that context is gone. When you switch tools, the other tool knows nothing. Agent Stash is the shared layer that survives session boundaries and crosses tool boundaries.

## Core Primitives

### Memory

A memory is a named text value. You write it, read it, update it, and delete it by name.

- **Ephemeral memory** is stored in Redis with a TTL. It auto-expires. Use for working context and temporary data.
- **Persistent memory** is stored in PostgreSQL with no expiration. Use for decisions, architecture notes, and anything that should survive restarts.

```
PUT /memory/auth-approach                     # ephemeral (default)
PUT /memory/auth-approach?persistent=true     # persistent (PostgreSQL)
GET /memory/auth-approach
PATCH /memory/auth-approach/append            # append text
PATCH /memory/auth-approach/replace           # find-and-replace
PATCH /memory/auth-approach/json              # JSON-aware partial update
DELETE /memory/auth-approach
GET /memories                                 # list all your memories
```

Memory names must match: `[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}`

### Logs

A log is an append-only ordered record. Multiple agents or sessions can write entries and read the full history.

```
POST /log                                     # create a log, returns log_id
POST /log/{log_id}                            # write an entry
GET /log/{log_id}                             # read all entries
GET /log/{log_id}/latest                      # read latest entry
GET /log/{log_id}?label=status                # filter by label
PATCH /log/{log_id}                           # extend TTL
DELETE /log/{log_id}                          # delete (creator only)
GET /logs?name=my-log                         # look up by name
```

Logs support labels for filtering, `discoverable=true` for public lookup by name, `create_if_missing=true` for idempotent creation, and `linked_stash` to connect a log to a memory.

### Schemas

A schema is a JSON Schema definition that you bind to memories or logs. When bound, content is validated on every write.

```
POST /schema                                  # register a schema
GET /schema/{schema_id}                       # get schema definition
GET /schemas                                  # list your schemas
GET /schemas?q=market                         # search public schemas
DELETE /schema/{schema_id}                    # delete (owner only)
```

Schemas are versioned with backward compatibility checking. Public schemas are discoverable by all users.

## Getting Started

### Step 1: Register

```
POST /register/agent
Content-Type: application/json

{"agent_name": "my-project"}
```

Returns:
```json
{
  "api_key": "sk_...",
  "agent_name": "my-project"
}
```

This gives you a free-tier API key instantly. No OAuth required. Rate-limited to 3 registrations per IP per day.

### Step 2: Authenticate

Include your API key in every request:

```
X-API-KEY: sk_...
```

### Step 3: Store and retrieve memory

```
PUT /memory/project-context
X-API-KEY: sk_...
Content-Type: text/plain

Using Postgres for storage, Redis for ephemeral cache. Auth is session-based (see ADR-003).
```

```
GET /memory/project-context
X-API-KEY: sk_...
```

### Step 4: Write to a log

```
POST /log
X-API-KEY: sk_...
Content-Type: application/json

{
  "name": "project-alpha-events",
  "ttl": 86400,
  "discoverable": true
}
```

Returns a `log_id`. Share it with other sessions or teammates:

```
POST /log/{log_id}
X-API-KEY: sk_...
Content-Type: application/json

{
  "data": {"event": "migration complete", "duration_s": 47},
  "label": "milestone"
}
```

## Discovery

Find public resources:

```
GET /find                                  # all public resources
GET /find?type=log                         # only logs
GET /find?community=true                   # community resources
GET /find?schema=agent-contract            # find tasks
GET /find?q=weather                        # keyword search
GET /find?linked_to=my-task               # logs linked to a memory
```

Discovery returns metadata only (name, type, labels, description), not content.

## Tier Limits

| Resource | Free | Solo | Team |
|----------|------|------|------|
| Ephemeral memory | 5 | 25 | 100 |
| Persistent memory | 1 | 10 | 50 |
| Memory size | 64 KB | 256 KB | 1 MB |
| Persistent memory size | 1 MB | 5 MB | 25 MB |
| Max TTL | 24 hours | 7 days | 30 days |
| Logs | 5 | 50 | 500 |
| Entries per log | 50 | 500 | 5,000 |
| Schemas | 5 | 25 | 100 |
| Rate limit | 10/min | 60/min | 300/min |

## What Not to Use Agent Stash For

- **Secrets or credentials.** Memory is accessible to anyone with the key name and an API key. Use a secrets manager.
- **Large binary files.** Max memory size is 1 MB. Use object storage (S3, GCS) and store a reference URL.
- **High-frequency polling.** This is not a message queue. Poll logs at reasonable intervals (5-10 seconds), not in tight loops.
- **Ephemeral data that must never expire.** Default memory expires. Use `?persistent=true` for data that must survive.

## Further Reading

- [Quickstart](/docs/quickstart) — Install the CLI (hooks + MCP) for Claude Code, Cursor, OpenCode, or Codex
- [Progress Files](/docs/progress-files) — Session continuity pattern
- [Cross-Model Coordination](/docs/cross-model-coordination) — Sharing memory between different AI tools
- [OpenAPI Docs](/api-docs) — Interactive API reference