Tool Reference

Stores a fact, note, or observation in long-term memory — a preference, a person, a decision, a deadline, or anything worth keeping across conversations.

Naming the people, projects or identifiers a fact is about (via entities) strengthens the cross-document connections that recall can later follow. If the fact clearly connects to something already stored, remember_connected is the better choice.

Health and safety facts — an allergy, a medication, an emergency contact — are automatically treated as high importance and marked protected, so they are never auto-evicted, whatever importance was passed.

This is the only tool that consumes your write quota, alongside remember_connected. It is subject to the target store's monthly write quota and memory cap.

Stores a fact that connects to things already in memory, and wires it into them.

Use it when a fact relates to an existing person, project or decision — someone's allergy that matters for a project's event, a decision that shifts a deadline. The text should be a self-contained sentence that names what it connects to, for example “Alex Rivera is allergic to shellfish (relevant to the Meridian team dinner)”, with those names also passed as entities. Those names become precise connections, so a later question about any one of them can surface this fact even when the wording shares no keywords.

That naming is what does the work, and it is identical to calling remember with entities.

It counts as one write, exactly like remember; the internal lookup it does is free.

Retrieves memories relevant to a question — people, projects, decisions, preferences, deadlines, earlier conversations. It is read-only, safe to call constantly, and never billed or counted against a quota on any plan.

By default it searches your active memory and every shared team space you can read, returning merged results each tagged with the space it came from; spaces_searched reports which stores were actually consulted. Pass space to narrow it — one space id, or a list of them to search just those.

Narrowing is worth doing when you know where the answer lives. Results are merged with a shared k across every space searched, so each extra space costs the relevant one depth: with many spaces you get each store's top hit or two rather than the best k from the store that actually knows. If a first recall shows the answer coming from one space, asking again scoped to that space returns more of its chain. Naming a space you cannot read is an error, never a quietly partial answer.

The default mode of auto runs a genuine dense-vector search plus the cross-document, multi-hop hits from entity-graph spreading — so the plain vector search you would have had is still running underneath, and you additionally get facts about related things that share no words with your query. auto returns at most k rows: the two channels are interleaved by rank and the response is capped, so a spreading hit is never simply appended past your budget. The other modes narrow the mix rather than the size: spreading returns only the entity-graph hits, each reporting its hop distance from the direct match; rag is a plain dense similarity search; flat is the bare substrate similarity.

Each returned memory carries when it was stored, which retrieval path found it, and — for a spreading hit — how many hops away it was and which entities connected it. Memories stored with a salience also report their importance band. The response as a whole carries a confidence band and, when nothing relevant is stored or only weak matches turn up, a notice saying so rather than letting the model invent an answer.

Time-filtered recall composes with everything else. Passing as_of or between scopes the search to a window without giving up the connection graph, so “what did we know about this in March, and what was it connected to?” is a single call. The window decides which memories come back, not which connections may be followed — a fact stored last week is still reachable through an entity first mentioned a year ago. It is applied before ranking, across the whole store rather than over a similarity prefix.

Compresses recurring memories into stable generalisations.

It groups memories that keep saying the same thing and represents each group as a single row in recall, tagged source: "semantic", which survives the eviction of any individual memory in the group. The text you see on such a row is a representative example — the most recent memory in the group, word for word — rather than a written summary; Cogni runs no language model on the server, so there is nothing to compose one. It carries no memory id (there is no single record to revise — correct the underlying memories instead) and no timestamp. A pass also runs automatically, roughly every 200 saved memories and whenever your store is loaded from disk, so calling it yourself is optional. It rewrites nothing you stored and creates no new billable memory.

This tool has no explicit plan check, but it only does anything when the consolidation feature is switched on, and that feature is restricted to Pro and above. On a Free plan it returns enabled: false and does nothing. Consolidating a team space requires a write role there.

Returns clusters of near-duplicate memories, so you and your assistant can walk through and tidy them.

The intended flow: for each cluster, write one merged summary with remember, then archive_memory each source in it — which is reversible via restore_memory. The review tool itself changes nothing at all. Protected, safety-critical and high-importance memories are excluded entirely and are never offered as candidates.

It is gated to Pro because it reveals memory content in bulk, in the same way list_memories does. For the same reason, using it against a team space requires a write role.

Soft-archives one memory: removes it from recall, but keeps it.

This is the reversible way to retire a source after merging a cluster during a consolidate_review walkthrough, or to retire a memory that has since been superseded.

Three tiers of memory are guarded, and a refusal says which one applied. safety means the deterministic safety floor caught it — an allergy, a medication, that class of fact. protected means it carries an explicit undeletable flag. high-importance means only that it was stored with a high salience band. The reply also carries overridable, so you can tell whether there is anything else to try.

Setting force retires a high-importance memory and nothing else. Safety and explicitly protected memories are refused whatever you pass: that tier exists precisely so that a tool argument cannot clear it. To retire one of those, correct it in place with update_memory, or ask the person whose memory it is.

Brings one archived memory back into active recall — the per-memory undo for archive_memory, for a reversible team-space delete, and for anything retention archived automatically.

The memory comes back under the same mem_id, with its original text, band, protected flag and creation time, so recall reaches it again and it survives a restart. It quietly does nothing for an unknown or not-archived id, or if the text now duplicates a live memory.

Undoing a team delete is free. When you bring back a memory a teammate deleted or replaced in a shared space, this works on every plan — it is the counterpart of deletion being free, so a team is never left able to delete but not recover. The Pro requirement applies only to restoring what the Free-tier retention window archived automatically, which is the keep-my-older-memories upgrade.

The current date and time, so your assistant can reason about when, not just what.

A model has no internal clock, so this is what it needs whenever an answer depends on the current time or an elapsed interval — a memory's age, how long since your last session, a deadline, a duration.

Estimates how long a task will take, grounded in what tasks of that type have actually taken before.

Once durations for a task type have been recorded, this returns the empirical median instead of a guess, with confidence that grows as the sample grows, and a summary of the full observed spread for reasoning about the tail. A model's own guess can be passed in, but it is used only as a fallback when there is no history at all.

Logs that a task of a given type actually took a given number of seconds.

This is what grounds future estimates in measured reality. Call it after finishing a task whose duration you can attribute to a repeatable type — or use effort_start and effort_stop to have the server do the measuring instead. It does not consume the memory write quota.

Starts measuring how long a task takes — the server stamps the start time and hands back a correlation id.

Called right before beginning a repeatable task, then paired with effort_stop when it finishes, this means the server computes the elapsed time and the model never has to guess a duration it cannot perceive. Open timers are persisted and survive a restart.

Stops a running timer and records its measured duration.

The result feeds straight into future estimate_effort calls. The space, if one was used, must match where the timer was started.

Lists tasks that were started but never stopped, with how long each has been open — how you find a forgotten timer or a still-running task.

Ranks candidate approaches by how long they will actually take, fastest first — so an agent picks the genuinely faster plan, not the one that merely looks faster.

Every step in every plan is calibrated against recorded history, with the model's own guess as a fallback. A step is only treated as unknown when it has neither — no recorded history and no supplied guess; a plan containing one of those is flagged incomplete and is not recommended.

The consequence is worth watching: a plan whose steps are all guesses is still marked complete and can still win the comparison, because a guess counts as an estimate. Check each plan's coverage figure — the fraction of its steps backed by real recorded history — before trusting a recommendation. A winner at zero coverage is the model ranking its own guesses.

Lists the task-type labels that have recorded history — the exact strings the estimate and compare tools can ground against.

Useful for discovering the label a duration was recorded under before estimating with it, since the labels are free text and must match.

Suggests a timeout in seconds for a repeatable task, derived from its recorded history rather than a guess.

The number is a chosen percentile of past durations (p95 by default) multiplied by a safety margin. It is a heuristic on the observed tail, not a guarantee — and with only a couple of recorded runs, confidence is low. With no history at all it returns null seconds and a note explaining why.

Checks whether a currently running task is overrunning, by comparing how long it has been going against the recommended timeout for its type.

It applies to a task started with effort_start and not yet stopped, identified by its correlation id.

The calibrated estimate for every task type with recorded history, in a single call.

It saves looping list_task_types and then estimate_effort for each label — useful for a summary of what an agent has learned about its own pace.

Lists the memory spaces you can reach — your private space plus any shared team spaces you belong to, each with your role and whether you can write.

This is how you find the space id to pass to remember or recall. It shows only your own memberships and reveals nothing about other members.

Takes no parameters.

Tells you whether anything has been written to a space since you last looked — how an assistant notices that a teammate’s assistant added something.

Recall is pull-only, so without this the only way to learn of someone else’s write is to run a full recall again and hope you picked a good moment. This reads the store’s write log directly: no search, no memory contents, and it never loads a store into memory — which is what makes it cheap enough to check often, where repeatedly running recall is not.

How to use it. Call it once with no since to get a cursor, then pass that cursor back on the next call. changed says whether to re-read and changed_spaces says which spaces are worth re-reading. When there is no usable baseline changed is null rather than false — that means “unknown”, so re-read.

By default it covers every space you can read in a single call. It reports only spaces you are a member of.

Creates a separate personal memory space — a “work” store kept apart from your everyday one.

The separation is physical, not a filter: each space is its own store, so memories in one genuinely cannot surface from the other. That is the same mechanism team spaces use.

A new space is not searched by default. Unqualified remember and recall keep using whichever space is currently active, so a new one is reached either by naming it or by switching to it with set_active_space. That is deliberate — if new spaces were folded into every search, nothing would actually be kept apart — but it does mean a memory filed in a space you are not in will not turn up until you switch.

The space id is generated for you from the name you give. There is a limit on how many you can have (three on Pro), because each space is a separate store with its own startup cost.

Switches which space unqualified remember and recall use — “switch to my work memory”.

The choice persists across sessions until you change it. Omit space to switch back to your main personal memory.

While a personal space is active your main memory is not searched by an unqualified recall, and vice versa — that separation is the point of having spaces at all. Shared team spaces are always searched either way, since those are collaborative by nature.

Permanently deletes one of your own personal spaces and everything in it.

Irreversible. The memories are erased, not archived, and there is no restore. Calling without confirm tells you how many memories would be lost rather than doing anything, so you can check first.

Only a personal space you created can be deleted here — not a shared team space, and not your main memory.

Shows your account's effective memory configuration: which feature flags and cognitive toggles are currently in force, what you have overridden, and what your plan permits you to enable.

Three feature flags can be switched: retention_policy, which is on by default on every plan, supersession, and consolidation on Pro or above. Both of the latter start off. The server also recognises four further names — anti_fabrication_notice, deep_chain_spreading, gist and meta_gist — which it reports but will not let you enable, because doing so would change nothing. The cognitive toggles reported alongside them — use_importance, use_decay and use_priming — are off by default. Read-only — use configure to change anything.

Takes no parameters.

Changes your account's memory configuration — turning feature flags on or off, and setting cognitive-overlay options.

Three features can be switched today: retention_policy and supersession on every plan, and consolidation on Pro or above. An unknown flag, or a feature above your plan, is rejected rather than silently ignored — so is a flag the server recognises but does not yet act on, because being told a switch worked when it did nothing is the worse outcome. Changes apply from your next recall.