# Use Korium with Codex / ChatGPT

Use Korium from Codex or ChatGPT to find earlier decisions and save what you learn. Choose the connection for the client running your task. The project instructions and shell hooks here are for local Codex work.

## Connect ChatGPT {#chatgpt}

For local work in the ChatGPT desktop app, MCP configuration is shared with Codex on the same host. Use the [Codex connection below](#connect) and check for an existing entry before adding another. Hosted ChatGPT conversations use a separate connection path, described in [OpenAI’s MCP guide](https://learn.chatgpt.com/docs/extend/mcp).

For a custom remote connection in ChatGPT:

1. In Settings, open Security and login and enable Developer mode, if your workspace permits it.
2. Open ChatGPT’s Plugins page and use the plus button to add a connection named Korium.
3. Choose a public MCP endpoint and enter `https://api.kyroco.ai/mcp`. Complete Korium’s OAuth sign-in and review the permissions.
4. Review the discovered tools. Start a new conversation and add the connection from the tools menu.
5. Ask for an actual Korium search, then follow [Your first memory](getting-started.html) to check a save and fresh-chat retrieval.

This is a custom connection, not an instruction to find a particular marketplace listing. If the controls differ or your organization disables them, follow [OpenAI’s connection instructions](https://developers.openai.com/plugins/deploy/connect-chatgpt) or ask the workspace owner. Do not copy a token from Codex.

## Use memory in a ChatGPT task {#chatgpt-task}

Connect the client first, then make the read and write steps explicit. Here is an illustrative brief-preparation task:

```
Search Korium for this project's agreed scope and open questions.
Use the source memories to prepare a brief for our next review.
Separate confirmed decisions from your suggestions.
After we review the brief, propose any new decisions worth saving.
Only capture the changes I approve, and show the memory IDs.
```

Inspect the search results and capture receipts, not just the assistant’s wording. Project files such as `AGENTS.md` and shell hooks belong to the local Codex workflow below; do not assume a hosted ChatGPT conversation reads or runs them. Use [the habit guide](make-it-automatic.html) to choose the right instruction mechanism for your client.

## 1. Connect Codex through MCP {#connect}

For a terminal setup, use these commands. In the desktop app, you can also add a remote MCP server through settings with the same URL. Use one connection method rather than installing duplicate entries with different names.

```
codex mcp add korium --url https://api.kyroco.ai/mcp
codex mcp login korium --scopes engram.read,engram.write,offline_access
codex mcp list
```

Finish the browser sign-in and consent, then return to Codex. The `list` command checks that the configuration exists; a real `agent_search` call checks that it works. If your app uses a different host from this terminal, configure the connection on the host running the task.

The CLI syntax was checked against Codex CLI 0.153.3. See [OpenAI’s MCP guide](https://developers.openai.com/codex/mcp) for client configuration details.

## 2. Give the project a memory rule {#instructions}

Add the [Korium project rule](make-it-automatic.html#rule) to the repository’s `AGENTS.md`. Use the real project scope. Keep the rest of the file intact.

Ask Codex to search for an existing decision before a small task. At the end, ask it to capture the useful outcome and show the returned memory ID. This checks the habit before you automate any of it.

## 3. Add the skills you need {#skills}

Ask Codex to fetch the Korium toolkit manifest and read the memory and code-search skills. Review their contents before adding them under your project’s `.agents/skills/` directory. Each skill has its own directory containing `SKILL.md`.

The code-search skill only helps after the repository has been indexed. The memory skill works through MCP and does not require `korium-cli login`. Keep that distinction when you adapt older toolkit instructions.

## 4. Add project hooks {#hooks}

Download <a href="examples/korium-session-start.sh" download>the session-start reminder</a> and <a href="examples/korium-task-end.sh" download>the task-end index script</a>. Read them, then save them in `.codex/hooks/`. The task-end script needs Bash, Git, [jq](https://jqlang.org/download/) and korium-cli 1.0 or later on your Mac.

Merge the following into `.codex/hooks.json`. Don’t replace existing hooks. If you only want memory reminders, leave out the Stop entry.

```
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/korium-session-start.sh\"",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.codex/hooks/korium-task-end.sh\"",
            "timeout": 120
          }
        ]
      }
    ]
  }
}
```

Review and trust the project’s hook definitions in Codex. Hooks from other config layers can also run, so check for duplicates. Current hook locations and trust behavior are described in [OpenAI’s hook documentation](https://developers.openai.com/codex/hooks).

## Which branch the task-end script indexes {#publishing-branch}

The task-end script indexes the branch the checkout is on when a task ends. Every branch has its own index, so indexing a feature branch never replaces the index of your main branch. The script skips a checkout that is not on a branch and a checkout with uncommitted changes: Korium indexes commits, so the first task end after you commit updates the index.

An earlier version of this script indexed only the branch named in a `korium.publishBranch` git setting. If you downloaded that version, download the script again: the current one does not read that setting, and you can remove it with `git config --local --unset korium.publishBranch`.

It can run beside the Git hook from `korium-cli hooks install`: each updates only the index of the branch it runs on, and when no file has changed since the last index, the second finds nothing to send. See [the code-index setup checks](release-status.html#code).

## What these hooks do {#behavior}

The SessionStart script adds a reminder to search memory and preserve useful learning. It does not make an authenticated search on behalf of the agent, and it does not claim that a search succeeded.

The Stop script reads the hook’s working directory and indexes a clean checkout of whichever branch it is on. When this Mac is not signed in, korium-cli returns at once without indexing, so the task is not held waiting, and the script says so. It also opens a sign-in in the browser and indexes once you finish, unless a sign-in is already open, you turned one down in the last hour, or there is no screen to show it on. It skips repeated Stop continuations, keeps CLI output off JSON stdout and reports a skip or failure without trapping the task. Codex expects JSON on a Stop hook’s standard output, which is why this script is used here rather than the plain command `korium-cli hooks install` prints for Claude Code.

The `--no-wait` flag does not prove publication. Even if the CLI exits zero, the hook tells you publication remains unverified. To enforce memory use more strictly, follow the [receipt-based checks](make-it-automatic.html#enforce); a code index update is not a memory capture.

## When the code index is behind {#stale-index}

When Codex searches code with `code_locate` and this checkout’s index is missing or behind, the answer says so and names the fix: run `korium-cli index` in the checkout, which indexes the branch the checkout is on. The answer carries this in its `next_step` field as well as in its warning. Korium also says it in the instructions it sends when a client connects. A Codex task that can run commands in the checkout can update the index itself, then search again naming the branch.

## 5. Test from a fresh task {#verify}

1. Start a new Codex task in the trusted project and confirm the memory reminder is present.
2. Ask it to retrieve the onboarding example with the Korium search tool.
3. Run `korium-cli index --dry-run` locally before enabling the task-end upload.
4. Finish a small code task. Check the hook output and the commit reported by a later code search.
5. Test the script with a harmless failing CLI stub before using it in a shared setup. A failed index should be visible and the task should still end.

If memory works but the CLI fails, troubleshoot the CLI connection on that Mac. Don’t remove the working MCP connection. See [authentication troubleshooting](troubleshooting.html#authentication).