Skip to main content
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

StatusMeaning
200Success
201Resource created
202Accepted (async operation enqueued)
400Invalid request body — check the error field for details
401Missing or invalid Authorization header
404Resource not found
409Conflict — resource already exists
413Payload too large (e.g. memory slot size exceeded)
503Feature not enabled — check the flag and enableHow fields in the response body
500Internal 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:
GroupPrefixPurpose
Sessions/session/*, /sessions, /observationsLifecycle and observation capture
Memory/remember, /forget, /memories, /profile, /export, /importMemory store management
Search/search, /smart-search, /context, /enrichRetrieval 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/*, /auditAudit trail and bulk deletes
Diagnostics/diagnostics/*, /health, /livezHealth and self-healing
Config/config/flagsRuntime feature flag inspection
The source of truth for all endpoint signatures is src/triggers/api.ts in the Agent Memory repository.