cogito-mem

API & MCP

Two things to do: store and find

One endpoint, POST /v1/memory, takes two operations. The same JSON works over HTTP, in Python, from the terminal and through the two MCP tools.

Store a nut: append

Terminal
curl -s localhost:7327/v1/memory -H 'Content-Type: application/json' -d '{
  "op": "append",
  "items": [{"author": "user", "text": "Let'\''s call the staging server acorn."}]
}'
{"items": [{"id": "01a155df-1bad-…", "created_at": "2026-10-19T20:34:07.405Z", "status": "added", "pieces": 1}],
 "took_ms": 4.8}

Find it again: query

Terminal
curl -s localhost:7327/v1/memory -H 'Content-Type: application/json' -d '{
  "op": "query", "text": "what did we call the staging server?"
}'
{
  "items": [{
    "text": "Let's call the staging server acorn.",
    "author": "user",
    "valid_at": "2026-10-19T20:34:07.405Z",
    "score": 1.0, "similarity": 0.53,
    "source": {"id": "01a155df-1bad-…", "start": 0, "end": 36},
    …
  }],
  "tokens": 9, "took_ms": 1.2
}

You get the original words, when they were said (valid_at) and where they came from (source). Nothing is rewritten.

Options

Everything is optional except the text.

When storing (each item)

authorwho said it, e.g. user, assistant, an agent's name
thread_idthe conversation it belongs to
titlea short label, e.g. the project
valid_atwhen it was said, for importing old chats
client_refyour id for it; the same one twice is stored once
retractsids of earlier items this one takes back

When finding

max_tokensthe basket: how much text comes back (default 1,000)
top_kat most this many items (default 10)
filterauthor, thread_id, valid_after, valid_before
as_ofsearch the memory as it was at that moment
namespacewhich hollow (default: yours)

Times are RFC 3339, e.g. 2026-10-11T09:00:00Z. The full reference, with errors and every rule, is in the specification.

MCP: the two tools Claude uses

ToolWhat it doesTakes
memory_appendSave to memorytext, title
memory_querySearch memorytext, valid_after, valid_before, max_tokens

Connect any MCP client, by command (stdio) or by URL (Streamable HTTP):

Terminal
claude mcp add --transport http cogito-mem http://127.0.0.1:7327/mcp
JSON
{
  "mcpServers": {
    "cogito-mem": { "command": "cogito-mem", "args": ["mcp"] }
  }
}
~/.codex/config.toml
[mcp_servers.cogito-mem]
command = "cogito-mem"
args = ["mcp"]

In Claude Code you don't need any of this: the plugin connects the tools for you.

Python

Python
from cogito_mem import Client

cogi = Client()   # the local service; it starts when needed
cogi.append([{"author": "user", "text": "The beta goes to ten design partners first."}])
cogi.query("who gets the beta first?")

Or Memory() to run the memory inside your own process, with the same handle({...}) requests.

Terminal

Terminal
cogito-mem query "staging server"
Terminal
cogito-mem append "Decision: ship the beta to ten design partners first."
Terminal
cogito-mem doctor

doctor checks every part of the install and says how to fix what is missing. The terminal command comes with uv tool install git+https://github.com/meridian21lab/cogito-mem.