> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Memory REST API — Overview and Authentication

> Agent Memory exposes 128 REST endpoints on port 3111. All endpoints are prefixed with /agentmemory/. Authenticate with a Bearer token when AGENTMEMORY_SECRET is set.

Agent Memory runs a local HTTP server on port 3111 with 128 REST endpoints. All endpoints are prefixed with `/agentmemory/`. You can use these endpoints to integrate Agent Memory into custom tools, scripts, or multi-agent pipelines — without requiring an MCP client or a native plugin.

## Base URL

```
http://localhost:3111/agentmemory
```

The REST API binds to `127.0.0.1` by default. To reach it from a remote host or sandboxed client, use the `--port <N>` CLI flag to change the port, or reverse-proxy the server and point `AGENTMEMORY_URL` at your proxy.

## Authentication

<Note>
  Authentication is optional for local use. If you never set `AGENTMEMORY_SECRET`, all endpoints accept unauthenticated requests.
</Note>

When `AGENTMEMORY_SECRET` is set in your config (`~/.agentmemory/.env`), all endpoints except `/livez` require a Bearer token:

```
Authorization: Bearer <your-secret>
```

Requests without a valid token return `401 Unauthorized`. Mesh sync endpoints (`/mesh/*`) additionally require `AGENTMEMORY_SECRET` to be set on **both** peers — they return `503` with `{ "error": "mesh requires AGENTMEMORY_SECRET" }` if the secret is absent.

### Health Check

The health endpoint requires authentication when `AGENTMEMORY_SECRET` is set:

```bash theme={null}
curl http://localhost:3111/agentmemory/health
# With auth:
curl -H "Authorization: Bearer <your-secret>" http://localhost:3111/agentmemory/health
```

Response includes the current service status, version, and optional circuit breaker state:

```json theme={null}
{
  "status": "healthy",
  "service": "agentmemory",
  "version": "0.9.27",
  "health": { ... },
  "viewerPort": 3113
}
```

<Tip>
  If `status` is `"critical"`, the endpoint returns HTTP `503` instead of `200`. Use this in your own health probes.
</Tip>

### Liveness Probe

A lightweight liveness endpoint for container orchestration — never returns `503`:

```bash theme={null}
curl http://localhost:3111/agentmemory/livez
```

```json theme={null}
{ "status": "ok", "service": "agentmemory", "viewerPort": 3113 }
```

## API Groups

<CardGroup cols={2}>
  <Card title="Sessions" icon="play" href="/docs/reference/api-sessions">
    Start and end sessions, list past sessions, capture observations, and link Git commits to session context.
  </Card>

  <Card title="Memory" icon="database" href="/docs/reference/api-memory">
    Save insights to long-term memory, recall past memories, delete obsolete entries, and export or import your full memory database.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/docs/reference/api-search">
    Hybrid BM25 + vector + graph search, generate context blocks for prompt injection, enrich file paths with related memories, and query the knowledge graph.
  </Card>

  <Card title="Graph" icon="share-nodes" href="/docs/reference/api-search#post-agentmemorygraphquery">
    Traverse the knowledge graph via `POST /agentmemory/graph/query`. Requires `GRAPH_EXTRACTION_ENABLED=true`.
  </Card>
</CardGroup>

## Content Type

All request bodies must be JSON. Include the `Content-Type` header on every `POST` request:

```
Content-Type: application/json
```

Responses are always JSON unless otherwise noted (the `/viewer` endpoint returns HTML).

## Error Responses

| Status | Meaning                                                                            |
| ------ | ---------------------------------------------------------------------------------- |
| `200`  | Success                                                                            |
| `201`  | Resource created                                                                   |
| `202`  | Accepted (async operation enqueued)                                                |
| `400`  | Invalid request body — check the `error` field for details                         |
| `401`  | Missing or invalid `Authorization` header                                          |
| `404`  | Resource not found                                                                 |
| `409`  | Conflict — resource already exists                                                 |
| `413`  | Payload too large (e.g. memory slot size exceeded)                                 |
| `503`  | Feature not enabled — check the `flag` and `enableHow` fields in the response body |
| `500`  | Internal error — rerun with `agentmemory --verbose` to see full stack traces       |

All error responses use the shape `{ "error": "<message>" }`. Feature-flag `503` responses carry additional fields:

```json theme={null}
{
  "error": "Knowledge graph not enabled",
  "flag": "GRAPH_EXTRACTION_ENABLED",
  "enableHow": "Set GRAPH_EXTRACTION_ENABLED=true and restart. Requires an LLM provider key.",
  "docsHref": "https://github.com/rohitg00/agentmemory#knowledge-graph"
}
```

## Full Endpoint Reference

Agent Memory exposes 128 endpoints across the following groups:

| Group       | Prefix                                                                | Purpose                                |
| ----------- | --------------------------------------------------------------------- | -------------------------------------- |
| Sessions    | `/session/*`, `/sessions`, `/observations`                            | Lifecycle and observation capture      |
| Memory      | `/remember`, `/forget`, `/memories`, `/profile`, `/export`, `/import` | Memory store management                |
| Search      | `/search`, `/smart-search`, `/context`, `/enrich`                     | Retrieval and context generation       |
| Graph       | `/graph/*`                                                            | Knowledge graph queries and management |
| Actions     | `/actions`, `/frontier`, `/next`, `/leases/*`                         | Multi-agent work coordination          |
| Signals     | `/signals/*`                                                          | Inter-agent messaging                  |
| Routines    | `/routines/*`                                                         | Workflow automation                    |
| Checkpoints | `/checkpoints/*`                                                      | External condition gates               |
| Snapshots   | `/snapshots`, `/snapshot/*`                                           | Git-versioned memory snapshots         |
| Team        | `/team/*`                                                             | Shared team memory                     |
| Slots       | `/slots`, `/slot`, `/slot/*`                                          | Pinned editable memory slots           |
| Governance  | `/governance/*`, `/audit`                                             | Audit trail and bulk deletes           |
| Diagnostics | `/diagnostics/*`, `/health`, `/livez`                                 | Health and self-healing                |
| Config      | `/config/flags`                                                       | Runtime feature flag inspection        |

<Note>
  The source of truth for all endpoint signatures is [`src/triggers/api.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/triggers/api.ts) in the Agent Memory repository.
</Note>