agentmemory-rest-api

rohitg00/agentmemory

HTTP REST API for agentmemory memory server; use when MCP is unavailable or integration requires HTTP.

What is agentmemory-rest-api?

The primary HTTP protocol for communicating with an agentmemory memory server. Use this when MCP is unavailable, you need a fallback integration method, or your host does not support MCP. Provides endpoints for saving memories, recalling information, and checking server liveness.

Save memories with content and concept tags via POST /remember endpoint
Recall memories using smart semantic search via POST /smart-search endpoint
Check server liveness with GET /livez endpoint
Support optional Bearer token authentication when AGENTMEMORY_SECRET is configured
Return standard HTTP status codes (201 for saves, 200 for reads, 400 for validation errors)

How to install agentmemory-rest-api

npx skills add https://github.com/rohitg00/agentmemory --skill agentmemory-rest-api

Prerequisites

agentmemory server running and listening on configured port (default 3111)
curl or HTTP client library for making requests
AGENTMEMORY_SECRET environment variable set if authentication is enabled

Claude Code

Cursor

Windsurf

Cline

How to use agentmemory-rest-api

1.Verify the memory server is running by calling GET http://localhost:3111/agentmemory/livez
2.To save a memory, POST to /remember with JSON body containing 'content' and optional 'concepts' array
3.To search memories, POST to /smart-search with JSON body containing 'query' string and optional 'limit' parameter
4.Include 'Authorization: Bearer $AGENTMEMORY_SECRET' header if AGENTMEMORY_SECRET is configured
5.Refer to REFERENCE.md for the complete endpoint list and method signatures

Use cases

Good for

Integrating memory persistence into a host system that does not support MCP protocol
Falling back to HTTP when MCP connection is unavailable or unreliable
Building custom memory clients in languages or environments without MCP libraries
Debugging memory operations by making direct HTTP calls to the server
Connecting external services to agentmemory without implementing full MCP support

Who it's for

Developers integrating agentmemory into non-MCP systems
Backend engineers building custom memory clients
Teams needing HTTP-based memory APIs for polyglot environments
Operators troubleshooting memory server connectivity

agentmemory-rest-api FAQ

Do I need to use this if MCP is available?

No. MCP is a bridge on top of this REST API. Use MCP if your host supports it; use REST only when MCP is unavailable or your integration requires HTTP.

Is authentication required?

By default, localhost connections are open and require no auth. Authentication is only enforced when the AGENTMEMORY_SECRET environment variable is set on the server.

What port does the API listen on?

The default port is 3111, but it is configurable via --port or --instance flags when starting the memory server.

What happens if I send unknown fields in the request body?

Unknown fields are safely ignored. The API handlers whitelist expected body fields and drop any extras.

What do the HTTP status codes mean?

201 is returned for successful saves, 200 for successful reads, and 400 for validation errors.

Full instructions (SKILL.md)

Source of truth, from rohitg00/agentmemory.

name: agentmemory-rest-api description: The agentmemory HTTP REST API surface, the primary protocol for talking to the memory server. Use when calling agentmemory over HTTP, when MCP is unavailable and you need a fallback, or when integrating a host that does not speak MCP. user-invocable: false

REST is agentmemory's primary surface. MCP is a bridge on top of it. Every memory operation has an HTTP endpoint under http://localhost:3111/agentmemory/*.

Quick start

# liveness
curl -fsS http://localhost:3111/agentmemory/livez

# save
curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{"content":"chose JWT refresh rotation","concepts":["jwt-refresh-rotation"]}'

# recall
curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H "Content-Type: application/json" \
  -d '{"query":"auth token strategy","limit":5}'

Auth

By default localhost is open and no auth is needed. When AGENTMEMORY_SECRET is set, every request needs Authorization: Bearer $AGENTMEMORY_SECRET. See agentmemory-config.

Conventions

Save returns 201, reads return 200, validation errors return 400.
Handlers whitelist body fields and drop unknown ones, so passing extra keys is safe but ignored.
The port is configurable with --port or --instance; streams, viewer, and engine derive from it.