Guide · Agent skill
How to use the agentmemory REST API agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The agentmemory-rest-api skill gives an AI agent a working reference for talking to the agentmemory memory server directly over its HTTP REST interface on localhost port 3111. It is written for developers and for people who need to debug memory calls with curl, and it assumes a server is already running. After this guide you will know how to install the skill, what it lets the agent do, and how to check that the server and your secret are working.
agentmemory REST APIrohitg00/agentmemory · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from the skill page and unzip it so the folder agentmemory-rest-api sits in ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Start the agentmemory server. Make sure a running agentmemory server listens on localhost:3111. The server is installed separately from this skill.
- 3Confirm liveness. Run the public liveness check at /agentmemory/livez to confirm the server responds.
- 4Provide the secret. Set AGENTMEMORY_SECRET, or rely on the secret file at ~/.agentmemory/secret, without printing its value.
- 5Save a test memory. Send a POST to /agentmemory/remember with a JSON body and expect a 201 response.
- 6Recall it. Send a POST to /agentmemory/smart-search with a query and limit and expect a 200 response.
What an agent skill is and what this one does
An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to perform a task. Once a skill is installed, the agent reads its description and loads the instructions when a request matches.
This skill covers the agentmemory HTTP REST surface. The source describes REST as the primary protocol for the memory server, with MCP as a bridge built on top of it. Every memory operation has an endpoint under http://localhost:3111/agentmemory/*. The skill gives the agent the endpoints for saving a memory and searching past memories, how to authenticate with a local secret, and the expected response codes.
Install the agentmemory-rest-api skill
Download the ZIP from the skill's page in this directory and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/agentmemory-rest-api/
- Project install: .claude/skills/agentmemory-rest-api/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the server and the secret before calling
Before any save or search, confirm the server is listening with the public liveness endpoint. The secret is read from the AGENTMEMORY_SECRET environment variable or, if that is unset, from ~/.agentmemory/secret. The source says the secret is generated into that file on first start when the variable is unset.
Protected endpoints require a bearer token even on localhost. Liveness does not.
- Requires curl in the shell
- Requires a running agentmemory server on localhost:3111, installed separately
- Requires the secret in AGENTMEMORY_SECRET or ~/.agentmemory/secret
curl -fsS http://localhost:3111/agentmemory/livezSave and recall a memory over HTTP
A save is a POST to /agentmemory/remember with a JSON body. A recall is a POST to /agentmemory/smart-search with a query and an optional limit. Writes must use Content-Type: application/json. Save returns 201, reads return 200, and validation errors return 400.
Use only documented fields. A successful response does not prove that an unsupported field was applied.
- Save: POST /agentmemory/remember with content and concepts
- Recall: POST /agentmemory/smart-search with query and limit
- Expected codes: 201 for save, 200 for reads, 400 for validation errors
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H "Authorization: Bearer $agentmemory_secret" \
-H "Content-Type: application/json" \
-d '{"content":"chose JWT refresh rotation","concepts":["jwt-refresh-rotation"]}'Trigger the skill with natural requests
The skill is marked as not user-invocable, so you do not type a slash command for it. The agent loads it when your request matches its description. Good triggers mention HTTP, curl, the REST API, or a situation where MCP is unavailable.
Phrase requests with the outcome you want. The agent then chooses the matching endpoint from the reference file.
- "Save this decision to agentmemory over HTTP using curl."
- "MCP tools are down. Search agentmemory for our auth token strategy through the REST API."
- "Show me the curl call to check that the agentmemory server is alive."
- "My host doesn't speak MCP. How do I store a memory in agentmemory?"
Authentication, safety and remote servers
The skill's example reads the secret into a shell variable and does not print it or enable shell tracing. The source says that for a remote daemon you need an explicit credential for that endpoint and HTTPS. A local-file secret must never be forwarded to another host, and authenticated redirects must not be followed to another host.
This skill runs no scripts, but it does use the network to call the local server. Treat it as a tool that can read and write your memory store.
- Runs scripts: no
- Uses network: yes, calls to localhost:3111 by default
- Never print the secret or enable shell tracing while calling the API
- Remote daemons need HTTPS and a deliberate credential plan
Troubleshoot common problems
If the agent reports that an MCP tool is not available, the bundled TROUBLESHOOTING.md walks through checks in order: identify the host, then restart or reload the affected host connection after configuration changes. The guide notes that native save and search do not prove the broader MCP tools are connected.
For endpoint details, open REFERENCE.md, which lists the 146 registered endpoints with their methods and paths. The file says it is generated from the source and should not be edited by hand. Two related skills, agentmemory-mcp-tools and agentmemory-config, cover MCP equivalents and local configuration.
- Check the port: REST defaults to 3111, changeable with --port or --instance
- The viewer defaults to 3113 and the engine WebSocket to 49134, which are different ports
- Validation errors return 400, so check field names against REFERENCE.md
What people use it for
- Debugging memory calls by hand with curl when an agent's results look wrong
- Integrating agentmemory into a script or app that calls HTTP rather than MCP
- Acting as a fallback path when the MCP tools are unavailable in your host
- Saving architecture decisions, such as an auth token strategy, to the memory store from a non-MCP tool
Frequently asked questions
How do I install the agentmemory REST API skill?
Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ for a personal install or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run the agentmemory REST API skill?
You need a running agentmemory server listening on localhost:3111, which is installed separately, plus curl in your shell. You also need the agentmemory secret, set in AGENTMEMORY_SECRET or stored in ~/.agentmemory/secret.
Is the agentmemory REST API skill free?
The skill is listed under the Apache-2.0 licence. This page does not state pricing, so check the repository's licence terms for the details of use.
Why do I get a 401 or authentication error when calling agentmemory?
Protected endpoints require bearer authentication by default, including on localhost. Make sure the secret in AGENTMEMORY_SECRET or ~/.agentmemory/secret matches the server, and that you send it as Authorization: Bearer. Only the liveness endpoint is public.
When should I use this skill instead of the MCP tools?
Use it when MCP is unavailable, when your host does not speak MCP, or when you are integrating agentmemory into a tool that calls HTTP. For a simpler setup inside Claude, the MCP tools or the main agentmemory setup are the better choice.
Can I use this skill with a remote agentmemory server?
The skill warns against it without care. A remote daemon needs an explicit credential for that endpoint and HTTPS, and a local-file secret must never be sent to another host.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who integrate agentmemory into HTTP-based tools, or who need to debug memory calls with curl when MCP is unavailable. It is not for non-technical users who only want memory in Claude, since the MCP tools or the main agentmemory setup are simpler. Pick something else if you need a hosted or remote memory service with no credential planning.
Download the skill