The brief is a push. It arrives once, unasked, and carries what your agent would never think to request. The MCP tools are the other half: the archive, on demand, from inside the session.
Runi registers its MCP server automatically for Claude Code, Codex, Cursor, Gemini CLI and OpenCode when you connect them. There is nothing else to install.
The six tools#
| Tool | Answers |
|---|---|
runi_search |
"What did we decide about X?", "What happened to this file?" Takes a query, a path, or both. |
runi_task |
One card whole, including the reasons and deferred items a briefing trims first. |
runi_continue |
Everything needed to pick up a piece of work: where it stands, what it depends on, open blockers, failed approaches, decisions and their reasons, files touched, the next action, and what did not fit. |
runi_team_status |
Who is working right now, as of this call and not as of session start. |
runi_brief |
The SessionStart briefing, rebuilt now. The fallback for a front end nothing can push to. |
runi_remember |
The one tool that writes. Records a decision and its reason, a discovery, a known issue or a convention, as proposed, in your name. |
Every tool answers through the same gate#
This is the load-bearing guarantee, and a pull path is exactly where a second, weaker gate gets written by accident.
A query narrows what is considered. It can never widen what is allowed.
There is one reader. Every tool assembles candidates and answers through the same packet builder, and the moderation pass, approval holds, the confidence floor, repository scope and own-session suppression all run after the filter, on every path. No second reader, no second gate.
Counts are reported after the gate for the same reason. A search saying "1 record was searched" over a record being held has just confirmed that something exists behind the hold, which is the fact the hold exists to keep.
The two opt-outs#
Two of the gate's rules are about relevance, not privacy, and two tools opt out of them:
runi_team_statusasks for your own other sessions. One person running two agents is the collision case it exists to catch.runi_continueasks for those and for finished sessions. A briefing is about now; a continuation is about where the work was left.
Neither opt-in touches the approval hold, the moderation pass, the confidence floor or repository scope.
Useful things to ask your agent#
| Say this | It calls | Worth it because |
|---|---|---|
| "Is anyone else working on this?" | runi_team_status |
The working tree cannot show you another machine. Ask before a refactor that spans files. |
| "What happened to this file?" | runi_search |
Answers "why is this like this" with the decision and its reason, which blame cannot. |
| "Continue the retention parser work." | runi_continue |
Replaces asking the author where they got to, including which dead ends not to re-walk. |
| "Remember this: we chose X because Y." | runi_remember |
Files it whole, with the reason, instead of leaving the extractor to guess at it later. |
What runi_remember will refuse#
- A decision with no reason.
- A title the workspace already holds.
- A write naming a path your ignore rules exclude.
- More than a bounded number of memories from one server process, so a single session cannot flood the workspace.
It never confirms. Everything it files is proposed until a person signs it. See Memory.
An empty result means Runi has nothing#
It does not mean nothing happened. Runi reads no files and no Git history. It knows only the sessions it observed and what their authors chose to share. When a search comes back empty, the reading is "this was never captured or never shared", not "this never occurred".
Troubleshooting#
Tool availability is not instruction. An agent calls a tool when something tells it to, which for Codex Desktop and VS Code is the guidance block in ~/.codex/AGENTS.md.
Check the block is installed and start a new session, or paste the same block into your repository's own agent guidance from Settings → Agents → Copy block.
Hooks re-read from disk on every run. MCP servers are long-lived and do not, so a session open across an update keeps running the previous daemon.
Restart those agent sessions. The doctor names them:
warn generation 1 MCP server still running the previous daemon:
pid 41288 (cursor, started 3 h ago) — restart those
agent sessionsA registration pointing at a daemon that is no longer there. Usually an agent disconnected by deleting the app instead of deselecting it first, or a registration made from the portable build.
Reconnect from an installed build, or disconnect the agent properly in Settings → Agents so the entry is withdrawn.