TulimoaTulimoaDocs
Docs menu

Memory tools and API

Reference for the eleven MCP tools of Tulimoa Memory and the HTTP endpoints for batch writes, document import, briefing and dashboard.

Last updated Sep 12, 2026

All tools live in the tulimoa namespace. Every tool call costs one call price ($0.002) and is charged before the tool runs; only tulimoa__link_account is free. initialize and tools/list never cost anything.

The routine that works best: recall at the start of a task, remember whenever something durable comes up, checkpoint before multi-step work, catch_up after a reconnect, and recall once more before finishing.

Tools marked write need a key with the write scope, and so do /ingest and /import. Keys from /register carry read and write. A read-only key gets an error for these calls and is not charged for them.

Remember and plan

tulimoa__remember(text, kind?, key?, durable?, entities?)write

Stores a memory: a fact, decision, preference or note (kind). A later remember with the same key replaces this one across the whole account. durable defaults to true. entities marks personal data explicitly as {value, etype} with person, email, phone, iban or custom, so it goes into the vault. Importance is inferred automatically, and text that looks like a credential is refused.

tulimoa__checkpoint(goal?, done?, next_steps?, open_questions?)write

Records where the agent stands. Pass only goal to set an objective, or the full form to snapshot progress so work can resume after a context reset. open_questions: [] clears the open loops of the session. At least one field is required.

tulimoa__forget(id?, key?, topic?, pii_token?)write

Removes an experience by id or key. With only topic it lists up to 8 matches and deletes nothing, so the agent can check first. With pii_token it crypto-shreds that person's data for good. Details in Privacy and deletion.

Recall and look back

tulimoa__recall(query?, limit?)

Returns what the memory knows about query, plus open loops and warnings. limit 1 to 25, default 8; without query it shows just the open loops. Searches the knowledge graph by meaning and by keyword, adds related knowledge, puts warnings about past trouble first and falls back to raw experiences while the graph knows little.

tulimoa__know(topic)

A cheap yes or no: does the memory hold anything about topic? Returns a confidence and the closest label, no contents. It checks consolidated knowledge only, so it answers no until the first night. If it says no, your agent does not know.

tulimoa__briefing(date?)

The morning briefing: what was consolidated, reinforced and forgotten, and which problems are still open. date as YYYY-MM-DD, the latest if omitted. A good first call after reconnecting.

tulimoa__timeline(from?, to?, session?, query?, limit?)

The literal history in order: raw experiences by date range, session or keyword. limit 1 to 100, default 30. Ranges older than 14 days are read from the archive, up to 62 days per request.

tulimoa__catch_up(since?)

Replays the events of the session since a cursor, up to 200, after a reconnect or a trimmed context. Without since it starts with the waking state.

tulimoa__self()

The agent's self-model: what it mainly works on, how the user likes things done, what it is good at and where it keeps running into trouble. Written during sleep once the memory holds at least 5 pieces of knowledge.

tulimoa__gaps()

Knowledge gaps: up to 8 topics that are named but thinly explored, and up to 8 open problems. Useful to decide what to find out next.

Account

tulimoa__link_account(email?, webhook_url?)write

Returns a code like ABCD-2345 that a person enters in the Tulimoa dashboard within 30 minutes to watch balance and warnings. email and webhook_url (https) receive the warnings directly. Free, no call price.

HTTP endpoints

Besides MCP, a few plain HTTP endpoints on https://memory.tulimoa.com. Writes use the same bearer key.

EndpointWhat it doesCost
POST /ingestBatch write of up to 100 experiences. Kinds: note, ingest, tool_call, tool_result, remember. durable defaults to false here.One call price per started 10 experiences
POST /importImports a document as {title?, text, session_id?}, split into chunks of about 900 characters, at most 400 chunks; anything beyond is dropped. Stored durably and consolidated on the next night.One call price per started 10 chunks
GET /briefing?key=The last 14 briefings as a web page.Free
GET /dashboard?key=Knowledge, recipes, contradictions, costs and sleep runs as a web page.Free
POST /register, POST /topupCreate an account or add balance via x402, see Connect.The amount you pay, credited in full
GET /.well-known/x402, GET /llms.txtMachine-readable terms and a short guide for agents.Free
Send tool results and notes in one batch
curl -X POST https://memory.tulimoa.com/ingest \
  -H "Authorization: Bearer tlm_mem_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "deploy-2026-09-12",
    "episodes": [
      { "kind": "tool_result", "text": "Deploy to staging succeeded", "payload": { "tool": "deploy" } },
      { "kind": "note", "text": "The customer prefers weekly summaries", "durable": true }
    ]
  }'

The response reports stored, dropped and quarantined counts plus the new ids. Tool results with payload.tool are what the memory learns recipes from, see Sleep, knowledge and the morning briefing.