Korium tool reference

Save: agent_capture

Captures one memory. Required fields are content, thought_type, source_agent, source_phase and importance. Optional context includes scope, confidence, evidence, rejected alternatives, who decided and metadata.

A successful acknowledgment includes thought_id. Check it and any refusal or warning before reporting success. The acknowledgment precedes later extraction and conflict analysis, so it does not certify that the new statement agrees with everything already stored.

See a complete capture example. If you attach relations, use the shape advertised by your actual client; the general relation tool and capture attachments do not necessarily expose the same schema.

Find: agent_search

{
  "query": "Why did we change the release check?",
  "scope": "onboarding.demo",
  "limit": 10
}

Search combines keyword and vector retrieval, with memory-aware ranking and related context. It returns source thoughts as well as retrieval information. Default result count is 10, with a maximum of 50.

Use focused questions. Check any partial or degraded-search signal, and inspect the underlying memories before treating a summary as an approved decision. See how ranking works.

Read the response, including its limits

This shortened, synthetic response illustrates the first-memory exercise. The returned id should match the thought_id from your own capture receipt. Fields omitted here still matter when you inspect a real response.

{
  "schema_version": "1",
  "query": "What must happen before release?",
  "result_count": 1,
  "thoughts": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "scope": "onboarding.demo",
      "type": "decision",
      "content": "Demonstration only: the data owner checks totals before release because the previous example had mismatched totals.",
      "provisional": true
    }
  ],
  "partial": null,
  "degraded_leg": null,
  "entities_partial": false,
  "related_entities": []
}

An incomplete response may contain this excerpt:

{
  "partial": true,
  "degraded_leg": "vector",
  "entities_partial": false,
  "what_this_means": "Some results may be missing from this search. Everything you saved is still here. If you do not see what you expected, run the search again in a few minutes, and try different words if it is still missing."
}

This is not enough to diagnose an outage. The same search flag can occur when a retrieval path matched nothing. Retry as advised, check the scope and wording, and say what is uncertain; do not turn an empty result into a definitive “none.”

related_entities: [] with entities_partial: true means the related-context fetch failed. With false, it still does not prove the world contains no relationship: the graph may not contain every relevant source. Use the memory and connection checks to inspect what was captured.

A tool returning is not always a successful save

A capture acknowledgment can contain queued: true, a thought_id, created_at, captured_by, conflict_flag and related_ids. The acknowledgment’s conflict flag is not a completed conflict check; background analysis happens later.

A plan or payload refusal may arrive in a normal tool response rather than as a protocol error. This shortened example is a refusal, not a memory receipt:

{
  "status": "rejected",
  "reason": "usage_restricted",
  "class": "quota"
}

quota means an allowance needs attention, payment means the payer needs to act, and payload means this capture needs changing. Repeating the identical call does not fix those conditions. Follow the message, preserve the unsaved work safely and do not mark the capture complete.

Validation, authorization and infrastructure failures can instead arrive as tool or protocol errors. Check both forms. If transport failed after a possible acceptance, search for the distinctive example or inspect its receipt before retrying a write, so an uncertain result does not become duplicate memories.

Inspect: korium_browse and korium_trace

korium_browse lists memories with pagination and filters for scope, type and status. Use it to inspect a project’s records or locate a specific kind of memory when semantic search is not the question.

korium_trace follows relationships from a memory ID. Choose forward, backward or both directions and a depth appropriate to the question. Maximum depth is 20; increasing it adds context, not certainty.

{
  "thought_id": "<memory-id>",
  "direction": "both",
  "max_depth": 3
}

For browse, status: "active" selects current records and status: "invalidated" selects records no longer current. Omitting the status filter lets you inspect both in the current interface. Check the original IDs and replacement information; this is different from expecting ordinary search to return every old record.

Use korium_stats for the memory statistics your connection is permitted to see. Statistics show activity and shape, not whether every statement is correct.

Connect: korium_relation

Links two existing memories with a typed relationship. For a correction, the source is the new memory and the target is the one it replaces.

{
  "source_id": "<new-memory-id>",
  "target_id": "<old-memory-id>",
  "relation_type": "supersedes"
}

Other supported relationships include contradicts, supports, derives_from and part_of. Read the live enum rather than assuming every domain relation is accepted by every tool.

Verify both IDs and the direction before writing a link. Use a trace afterward when the relationship will guide future decisions.

Import: korium_hydrate

Imports an array of prepared memories. Each entry includes the content, memory type, source agent, phase and importance, with optional scope and capture attribution. Review the batch before sending it.

Imports use total room rather than the ordinary monthly save allowance. A batch that does not fit is refused as a whole. Follow the tool’s current batch limits and your plan’s import entitlement instead of splitting a refusal into blind retries.

Names and domain vocabulary

korium_list_provenance lists recorded agent names or work phases. korium_set_provenance_alias lets a tenant administrator adjust the displayed name without rewriting the stored record. Use this for a typo or rename, not for changing who actually made a decision.

korium_register_vocabulary adds a domain entity or relation type based on a core type. Register the entity types before using them to constrain the ends of a relation. Choose words your team already uses and test extraction with representative examples.

Vocabulary hints have size and count limits in the live schema. More synonyms are not automatically better. An overly broad label can connect unrelated things with greater confidence, which is the opposite of what you want.

Locate code: code_locate

{
  "repo": "rootsha:<repository-root-sha>",
  "head_sha": "<git-rev-parse-HEAD>",
  "branch": "feature/refunds",
  "query": "RefundPolicy calculateRefund",
  "limit": 5
}

Returns symbol locations and the index commit, along with freshness information. Pass the actual checkout SHA and the repository identity from the CLI. Verify stale candidates locally before relying on their line numbers.

Each branch of a repository has its own index. branch is optional: send it to search that branch’s index, or leave it out and the repository’s trunk answers. HEAD is refused, because it is what a detached checkout prints rather than a branch. The answer’s branch and is_trunk say which index answered, and freshness is judged against that branch’s own indexed commit. If the repository has no index for the branch you named, nothing is searched: staleness.reason is branch_unknown and known_branches lists the branches it does hold. A repository indexed only on branches, with no trunk, answers a search that names no branch with repo_unknown and known_branches.

When the answer means this checkout’s index is missing or behind (anchor_candidates, sha_miss, branch_unknown or repo_unknown), it carries next_step, an object with four strings: command is always korium-cli index, why says what is missing, how says where to run it, and install says where to get korium-cli. staleness_warning ends with the same how and install sentences. A current answer has no next_step.

Korium also sends these instructions to a client when it connects: “Search code with code_locate. When a code_locate answer carries next_step, next_step.why says what is missing and next_step.how says where to run next_step.command. If the answer lists known_repositories and one of them is the repository you are in, send that as repo instead of indexing. After korium-cli index finishes, search again with branch set to the branch the checkout is on. korium-cli runs on the person's Mac, and when that Mac is not signed in it opens a sign-in in their browser and waits for them. To keep the index current after each ordinary commit, suggest the person run korium-cli hooks install; do not run it for them, because it adds a git hook to their repository, and to every repository on their Mac when git shares one hooks folder between them.”

korium-cli search is the terminal path to code-location search, not a substitute for memory retrieval.

List code indexes: code_repositories

Lists the workspace’s code indexes, one entry per branch index: a repository indexed on its trunk and two branches is three entries. It takes no query.

{
  "limit": 50
}

Each entry carries repo_display (the name korium-cli registers), repo_fingerprint (the repository identity, such as rootsha:…), repo_id, branch, is_trunk, indexed_by_account_id, indexed_at and indexed_git_sha (when and at which commit it was last indexed), reading_version, last_used_at (the last search it answered, to the hour), last_sealed_at (when the idle clock started: the last completed index, or the creation of an index that never completed, or the day a former trunk stopped being the trunk, whichever is latest), days_until_reap, card_count and file_count. reading_version is the version of the client that read every symbol the index holds, and null when that is unknown or more than one did. days_until_reap is how many whole days are left before an idle branch index is removed, 0 meaning the next sweep; it is null for the trunk, which is never removed for being idle.

Entries are ordered by repo_fingerprint, then branch. limit is 1 to 100, default 50. When there are more, send the answer’s next_cursor back as cursor for the next page; it is null on the last page. A workspace with no index answers repositories: [] and count: 0. From the terminal, korium-cli repos shows the same list.

Delete a branch index: code_delete

Deletes one branch’s code index, the trunk included. Your git branch and source are not touched.

{
  "protocol_version": "1",
  "repo_fingerprint": { "root_sha": "<repository-root-sha>" },
  "branch": "feature/refunds"
}

It deletes that branch’s index and nothing else, and when it refuses it deletes nothing. A refusal is status: "rejected" with a reason and a detail sentence:

The last two are answered by sending the same delete again with intent: "truncate", which says you mean it; korium-cli delete BRANCH --allow-removals does that. The others are not. On success status is deleted and remaining_branches lists what the repository still holds. Besides this tool, only the idle sweep removes an index: a branch 14 days after the later of its last completed index and, for a former trunk, the day it stopped being the trunk. It never removes a trunk.

Build an index: code_submit

korium-cli index handles the submission protocol. Use it rather than constructing code-index uploads yourself. Two fields matter if you read the protocol:

• trunk, sent when the upload starts, names the branch your remote calls its default. The branch equal to it becomes the trunk once that index is completed by an account allowed to publish it. Without trunk, the first branch a repository ever indexes becomes its trunk, and later uploads that don’t name it never move it. korium-cli sends trunk only when git records the remote’s default branch.
• reading_version, also sent when the upload starts, is the version of the client that read the files. code_repositories lists it for the branch once a completed index shows that version read every symbol the branch serves.

retrack is refused: each branch is its own index, so there is nothing to move.

Fetch instructions: korium_get_toolkit

Use op: "guide" for the introduction, op: "manifest" for the file list and README, and op: "file" with a returned rel_path for one file. The manifest includes hashes that can be checked before writing fetched files locally.

The starter toolkit contains text instructions, skills, a sample agent and hook guidance. It does not install the CLI, authenticate another client or run a workflow. Review its contents against the current client and preserve existing project files when adopting it.

If your account exposes workflow configuration tools, use them for the configuration they advertise. A config read is not a skill download or a workflow execution.