agentmemory-rest-api

rohitg00/agentmemory

HTTP REST API for agentmemory memory server—save and recall agent knowledge over HTTP.

What is agentmemory-rest-api?

The primary HTTP protocol for interacting with agentmemory when MCP is unavailable or unsupported. Provides endpoints to save memories, search recall, and check server liveness on localhost:3111.

Save memories with content and concept tags via POST /remember
Search and recall memories with semantic queries via POST /smart-search
Check server liveness with GET /livez
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 localhost:3111 (or configured port)
Optional: AGENTMEMORY_SECRET environment variable if authentication is enabled

Claude Code

Cursor

Windsurf

Cline

How to use agentmemory-rest-api

1.Check server liveness: curl http://localhost:3111/agentmemory/livez
2.Save a memory: POST to /remember with JSON body containing content and optional concepts array
3.Search memories: POST to /smart-search with query string and limit parameter
4.Include Authorization header with Bearer token if AGENTMEMORY_SECRET is set
5.Parse response status codes: 201 for successful saves, 200 for reads, 400 for validation errors

Use cases

Good for

Integrating agentmemory into hosts or systems that do not support MCP protocol
Falling back to HTTP when MCP is unavailable or unreliable
Building custom memory clients that communicate over standard REST
Debugging memory operations with curl or HTTP clients
Connecting non-Node.js applications to agentmemory

Who it's for

Developers integrating agentmemory into non-MCP systems
Teams needing HTTP-based memory fallback
Custom agent framework builders
DevOps and integration engineers

agentmemory-rest-api FAQ

What port does agentmemory listen on by default?

Port 3111 by default. Configure with --port or --instance flags; streams, viewer, and engine ports derive from it.

Do I need authentication to use the REST API?

No authentication is required by default on localhost. When AGENTMEMORY_SECRET environment variable is set, include Authorization: Bearer $AGENTMEMORY_SECRET in all requests.

When should I use REST API instead of MCP?

Use REST when MCP is unavailable, unsupported by your host, or when you need a fallback protocol. MCP is built on top of REST.

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

Unknown fields are safely ignored; handlers whitelist expected body fields and drop the rest.

Where is the full endpoint reference?

See REFERENCE.md in the agentmemory repository, generated from src/triggers/api.ts.

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.