Reference

Tools reference

Seven memory primitives plus a health check. Each MCP tool has an equivalent REST endpoint — they call the same service and are behaviour-identical. MCP calls are POST /api/mcp with {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"…","arguments":{…}}}; the tool result is a JSON string in result.content[0].text.

Tool	Purpose	REST
`memory_remember`	Save a memory (sourced ⇒ fact, unsourced ⇒ hypothesis).	`POST /memories`
`memory_recall`	Semantic top-k with provenance + trust.	`POST /memories/recall`
`memory_list`	Browse / audit recent rows (no search).	`GET /memories`
`memory_supersede`	Correct: new row replaces old, old kept.	`POST /memories/{id}/supersede`
`memory_forget`	Tombstone a memory with a reason.	`POST /memories/{id}/forget`
`memory_observe`	Fresh observation; promotes hypothesis → fact.	`POST /memories/{id}/observe`
`memory_consolidate`	Compress episodic → semantic, preserving the doubt.	`POST /memories/consolidate`
`ping_memory`	Health check (agent, embed model, backend).	—

memory_remember

Save a memory. With a source it is a fact (observed now); without one, a hypothesis. Honours the anonymous-24h durability rule.

POST /api/v1/memories

Argument	Type	Notes
`content` *	string	The memory text — a self-contained statement.
`namespace`	string	Sub-scope; defaults to the agent default.
`source`	string	Presence ⇒ fact; absence ⇒ hypothesis.
`confidence`	number	0..1. Default 1.0 (fact) / 0.5 (hypothesis).
`invalidation_tag`	string	temporal \| paradigm \| architectural \| observational.
`invalidation_condition`	string	The test that would retire this memory.
`kind`	string	`semantic` or `episodic`.
`parent_id`	integer	Derived-from id; unsourced derivations inherit hop_count+1.
`ttl_hours`	number	Shorter lifetime for a scratch note (anonymous capped to 24h).

tools/call · memory_remember

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"memory_remember",
  "arguments":{
    "content":"The deploy script restarts php8.4-fpm after composer install.",
    "source":"runbook",
    "invalidation_condition":"delete if deploys move to a zero-downtime reload"
  }
}}

result (decoded from result.content[0].text)

{
  "id": 42, "status": "fact", "source": "runbook",
  "content": "The deploy script restarts php8.4-fpm after composer install.",
  "namespace": "proj", "kind": "semantic", "confidence": 1.0,
  "learned_at": "2026-10-26T12:00:00+00:00",
  "last_observed_at": "2026-10-26T12:00:00+00:00",
  "hop_count": 0, "parent_id": null,
  "invalidation_condition": "delete if deploys move to a zero-downtime reload",
  "expires_at": null, "ephemeral": false, "expiry": "permanent"
}

memory_recall

Embed the query and return the nearest memories, facts first, each with provenance, a cosine similarity, a trust hint and its durability.

POST /api/v1/memories/recall

Argument	Type	Notes
`query` *	string	Natural language.
`namespace`	string	Restrict to one sub-scope.
`limit`	integer	1..50, default 8.
`include_retired`	boolean	Also return retired/superseded rows.
`include_expired`	boolean	Also return expired ephemeral rows.
`status`	string	Restrict to one status.

tools/call · memory_recall

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"memory_recall",
  "arguments":{"query":"what happens to php-fpm on deploy?"}
}}

result (decoded)

{
  "query": "what happens to php-fpm on deploy?",
  "results": [{
    "id": 42, "status": "fact", "source": "runbook", "similarity": 0.89,
    "content": "The deploy script restarts php8.4-fpm after composer install.",
    "confidence": 1.0, "hop_count": 0, "unattributable": false,
    "trust": "fact: sourced and observed — trustworthy, but still falsifiable…",
    "ephemeral": false, "expiry": "permanent"
  }]
}

memory_list

Recent/filtered rows — no semantic search. Defaults to live rows (fact + hypothesis); pass status="retired" to inspect tombstones.

GET /api/v1/memories?namespace=&status=&include_expired=&limit=

tools/call · memory_list

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"memory_list","arguments":{"namespace":"proj","limit":20}
}}

memory_supersede

Save a new memory that replaces id. The old row is retired (kept, linked), never hard-deleted. Accepts the same provenance fields as memory_remember.

POST /api/v1/memories/{id}/supersede

tools/call · memory_supersede

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{
  "name":"memory_supersede",
  "arguments":{"id":42,"content":"The admin dashboard moved to /manage.","source":"routes"}
}}

result (decoded)

{
  "superseded": {"id": 42, "status": "retired", "superseded_by": 57},
  "new": {"id": 57, "status": "fact", "parent_id": 42,
          "content": "The admin dashboard moved to /manage.", "source": "routes"}
}

memory_forget

Tombstone a memory (retire, not destroy) with a reason. Kept for history, reachable via include_retired.

POST /api/v1/memories/{id}/forget

tools/call · memory_forget

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
  "name":"memory_forget","arguments":{"id":42,"reason":"staging decommissioned"}
}}

memory_observe

Record a fresh observation of id: stamp last_observed_at and bump confidence. The only path that promotes a hypothesis to a fact.

POST /api/v1/memories/{id}/observe

tools/call · memory_observe

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{
  "name":"memory_observe","arguments":{"id":42}
}}

memory_consolidate

Compress episodic memories (things that happened) into semantic ones (distilled lessons) — without eating the doubt. Worthy episodic rows are clustered by namespace; each cluster is summarized by a cloud model into one new semantic memory. The structured facets are derived in code, not by the model, so the uncertainty always survives:

status is always hypothesis — a summary is derived, never a fresh fact (only memory_observe promotes);
confidence = the minimum of its sources (never inflated);
invalidation_tag / invalidation_condition = the union of every source's (no doubt dropped);
hop_count = max(sources)+1 and last_observed_at = null, so it reads as unattributable until re-observed;
the source episodes are superseded (retired + linked), kept and addressable — never deleted.

POST /api/v1/memories/consolidate

Argument	Type	Notes
`namespace`	string	Restrict to one sub-scope. Omit to consolidate every namespace with enough episodic rows.
`dry_run`	boolean	Preview clusters + derived facets without writing (default false).
`max_clusters`	integer	Cap how many namespace clusters to consolidate in one call.

tools/call · memory_consolidate

{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{
  "name":"memory_consolidate",
  "arguments":{"namespace":"proj","dry_run":false}
}}

result (decoded)

{
  "dry_run": false, "clusters": 1, "sources_consolidated": 3,
  "semantic_created": 1, "model": "glm-5.3-flash:cloud",
  "details": [{
    "namespace": "proj", "source_ids": [12, 14, 17], "sources": 3,
    "semantic_id": 21, "status": "hypothesis", "confidence": 0.6,
    "invalidation_tag": "temporal, architectural", "hop_count": 1, "parent_id": 12
  }]
}

ping_memory

Health check: echoes a message and reports the acting agent, the embedding model, and whether the embedding backend is reachable.

tools/call · ping_memory

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{
  "name":"ping_memory","arguments":{"message":"hello"}
}}

NextREST API → AlsoConnect your agent →