Agent Memory REST API — Overview and Authentication

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

Authentication is optional for local use. If you never set AGENTMEMORY_SECRET, all endpoints accept unauthenticated requests.

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:

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:

{
  "status": "healthy",
  "service": "agentmemory",
  "version": "0.9.27",
  "health": { ... },
  "viewerPort": 3113
}

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

Liveness Probe

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

curl http://localhost:3111/agentmemory/livez

{ "status": "ok", "service": "agentmemory", "viewerPort": 3113 }

API Groups

Sessions

Start and end sessions, list past sessions, capture observations, and link Git commits to session context.

Memory

Save insights to long-term memory, recall past memories, delete obsolete entries, and export or import your full memory database.

Search

Hybrid BM25 + vector + graph search, generate context blocks for prompt injection, enrich file paths with related memories, and query the knowledge graph.

Graph

Traverse the knowledge graph via POST /agentmemory/graph/query. Requires GRAPH_EXTRACTION_ENABLED=true.

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:

{
  "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

The source of truth for all endpoint signatures is src/triggers/api.ts in the Agent Memory repository.

​Base URL

​Authentication

​Health Check

​Liveness Probe

​API Groups

Sessions

Memory

Search

Graph

​Content Type

​Error Responses

​Full Endpoint Reference

Base URL

Authentication

Health Check

Liveness Probe

API Groups

Content Type

Error Responses

Full Endpoint Reference