Browse the documentation
Memory works, but the CLI fails
That is possible because they use separate connections. Your assistant authenticates to the MCP service. The CLI authenticates independently on the Mac where it runs.
Check memory with the assistant’s real agent_search tool. Check the CLI with korium-cli status. Do not remove a working MCP connection to repair the CLI’s keychain sign-in.
The login keeps asking again
Record the client version, service address, time and exact error. Check whether the failure happens during discovery, browser authorization, the local callback, token exchange or refresh. Those observations are more useful than guessing a token lifetime.
Update an outdated client and retry the failing operation once. If reauthorization is needed, use that client’s own login: codex mcp login korium for the Codex MCP entry, /mcp in Claude Code, or korium-cli login for the Mac CLI. Keep these flows separate.
If the error names an authorization-server issuer, inspect whether the client retained the issuer and discovery metadata in the format it expects. A field being present somewhere in a response does not prove the client stored it correctly. Don’t paste the raw credential file to demonstrate it.
A refresh token can be rejected for reasons other than age, including revocation, rotation races or mismatched client state. Keep the failure evidence and ask for help if a fresh connection repeatedly breaks.
The tool is missing
Confirm the connection is enabled in the host running the task and that it requested the required scopes. A read-only token will not expose writing tools such as capture. The tool prefix may differ from the name in another assistant.
Use the live tool list. Don’t type a tool name from somebody else’s screenshot and assume it must exist in your client. Reauthorize with the appropriate scope only if the connection should have that permission.
Search is empty or returns the wrong material
Check the account, then the scope, then the question. Search for distinctive words from a known memory and compare with a browse operation. Confirm the earlier capture actually returned a successful memory ID.
A new capture may still be undergoing background extraction or indexing, so wait a few seconds and search again. A search itself answers in full or reports a failure; there is no half answer to read.
If the result is factually wrong, check the source and replacement chain. A confident answer is not a reason to overwrite a reviewed decision.
The save returned an ID, but the next step is not ready
Keep the receipt and the exact operation that did not work. Saving, search, graph links and code publication have different completion checks. Do not submit repeated copies of the same material while diagnosing a read.
| What you see | What to check next |
|---|---|
| Capture refused or no successful receipt | Read the error or rejection class. Fix permission, allowance or payload before treating it as saved. |
| Capture receipt, but no expected search hit | Compare account and exact scope, search distinctive wording, and inspect the record with browse after processing. |
The record is present in history but has invalid_at | It is no longer current. Browse with status: "invalidated" and inspect any replacement links; supersession and duplicate processing are different possible causes. A memory retired by the earlier age-based expiry, which no longer runs, shows ttl_expired as its reason. |
| Both an original and its correction are inactive | The correction exercise has not passed. Keep both IDs and the trace; ask support to inspect the reason and surviving replacement rather than saving a third copy. |
| Search reports entities_partial | The memories are complete; the related-entity lookup is not. Do not infer an exact zero for the related items. |
| Correction saved, but relation or trace failed | Keep both IDs. Confirm both records are available to the relation operation, then verify the link; do not create another correction merely to retry it. |
| CLI finishes, but the indexed commit is old | Publication remains unverified. Follow the final CLI message and check a known symbol at the expected commit. |
A timestamp alone does not identify the cause. korium_browse shows when a record stopped being current, but not why or which memory a duplicate folded into; report that missing visibility rather than inventing a diagnosis.
If processing does not settle, send the time, receipt ID, client version and exact failure through the support path. Do not send the private memory content unless you have agreed to share it.
Code search points at the wrong version
Read the indexed commit and compare it with git rev-parse HEAD. Verify returned candidates in the local file before using the line range. An older index can still be useful, but it is not proof of the current implementation.
An unknown repository needs the correct identity or its first index. An unindexed commit needs an update. An unsupported file type needs local text search. Don’t solve all three by repeatedly changing the wording of the query.
Each branch has its own index. Read the branch named in the answer as well as the commit. A search that names a branch Korium holds no index for searches nothing and lists the branches it does hold; so does a search that names no branch in a repository with no trunk index, for example because it was deleted. Index the branch you need, or name one of those listed. When an assistant’s code_locate answer says the index is missing or behind, its next_step says to run korium-cli index in the checkout.
korium-cli index --retrack is gone. korium-cli refuses it and sends nothing, because there is no single index to move between branches. Run korium-cli index from the branch you want indexed.
If you used --no-wait, check whether publication completed. “Accepted” and “searchable” are separate stages.
The Mac CLI cannot run or sign in
Check korium-cli version and the installed path. Use the supported package from your dashboard rather than a copied standalone binary. The installed app’s signing and keychain access matter.
You don’t need to run korium-cli login before other commands. index, search, delete and repos open the browser sign-in when this Mac is not signed in, or when Korium no longer accepts the saved sign-in, and then carry on. If you decline, or don’t finish within three minutes, the command stops and says what it did not do. For search, delete and repos that means nothing was done; for index it means korium-cli stopped before it could confirm the index is up to date: some or all of the upload may already have gone, so don't assume either way. Run it again when you are ready.
Compare status in a normal terminal with the same command in the failing execution context. A sandbox or background service can have different keychain access. Grant only the access that setup needs; don’t solve it by exporting a token.
If indexing is refused, read the stated reason. A removal guard, a size limit on one upload and an invalid repository root are not authentication failures. Preview with --dry-run before changing the scope or permitting removals.
The hook is silent or will not stop
Confirm the file exists where the configured command resolves, the project is trusted and the required tools are on PATH. Run the script with sample input outside the agent to separate a script failure from a client configuration problem.
Keep JSON stdout clean for hooks that expect it. Send diagnostic output to stderr. Check stop_hook_active before asking a Stop hook to continue again.
Korium’s Git hooks and the Claude Code Stop hook from korium-cli hooks install never wait for a sign-in. On a Mac that is not signed in, they open the sign-in in your browser in the background and finish at once. If you declined that sign-in within the last hour, or the Mac cannot open a browser, as over ssh, they print one line saying the index was not changed and which command to run yourself to sign in, such as korium-cli index; over ssh it says to run it at the Mac itself. Run a korium-cli command yourself, other than help, version or licenses, and the hooks may ask again.
The provided task-end script reports an indexing failure and allows completion. If you add a stricter memory reminder, test unavailable-service and quota-refusal cases as well as the happy path.
What to send us
- The command or tool that failed, without credentials.
- Your client and CLI versions, operating system and server address.
- The exact error, time and any request ID.
- Whether the same operation works in another execution context.
- The indexed commit and requested commit for a code-search problem.
Remove private memory contents and customer source material unless you have explicitly agreed to share them. Send the useful diagnostic details to support@kyroco.ai.
Use the setup checklist before changing an automated workflow. Check your installed client’s help if its interface differs.