API Reference

The memory REST API reads and writes project notes. Use MCP for keys limited to selected workspaces or projects.

Authentication and scope

Send an API key in Authorization: Bearer <api-key>. Node retrieval, search and write endpoints require an account-wide API key; writes also require read-write access. A browser session JWT does not replace the key on these endpoints. Project authorization still applies.

A scoped-key 403 is a boundary, not an instruction to widen permissions. Use MCP for that scoped key. Ask the administrator if the REST workflow is appropriate.

Memory endpoints

GET /api/v1/memory/search: q and projectId are required; limit is 1–50. Returns relevant nodes with nodeId, label, content, score and metadata. A score measures similarity, not truth.

POST /api/v1/memory/add: projectId and content are required; tags and type are optional. Content is limited to 10 KiB in UTF-8. A successful response is HTTP 201 with nodeId, content, tags, type, createdAt and updatedAt.

GET /api/v1/memory/list: projectId is required; limit is 1–200 and offset is optional. The response contains nodes and total.

GET /api/v1/memory/:id reads one node; GET /api/v1/memory/related/:id finds related notes. DELETE /api/v1/memory/:id removes a node and requires write permission. Do not use deletion to test a connection.

GET /api/v1/memory/usage returns account memory usage. Unlike the node endpoints, it accepts a session JWT or an API key. The response contains used, limit and tier; limit=null means no node limit.

Errors and retries

400 means invalid input; correct the named field. 401 means missing or invalid credentials. 403 means the requested access or key scope is refused. A 404 can mean an unavailable node; it does not grant permission to search other projects.

Search can be unavailable while its service is down. Keep the original query and retry later. Treat an uncertain write outcome separately: check the project before resending, because an add request can create another node.

curl --get '/api/v1/memory/search' \
  -H "Authorization: Bearer $NEKOMIND_API_KEY" \
  --data-urlencode 'q=customer feedback' \
  --data-urlencode 'projectId=YOUR_PROJECT_ID' \
  --data-urlencode 'limit=5'