Capturing agent conversations

The conversations you have with your AI agents are full of knowledge: decisions, reasoning, things you worked out together. There are two ways to keep them in your brain, an easy one that works today, and an automatic one for when you want it to happen without thinking.

The easy way: just ask

At the end of a conversation, tell your connected agent to save it:

“Save a summary of what we worked out to my brain.”

The agent writes a tidy page into your brain, following the ingest skill, the same as any other thing you ask it to save. No setup, nothing to install. This is all most people need. It lands in your own work brain, so anything captured this way stays yours until you decide to promote it.

The automatic way: a session hook (advanced)

If you would rather have every session captured without asking each time, Claude Code can do it for you with a hook: a small command it runs automatically when a session ends. Setting this up means creating a short script and editing a settings file, so it is a step up in effort. If you are comfortable with a terminal it takes a few minutes; if not, it is a good one to hand to a developer, or just use the easy way above. First, the one step that is the same on every system:

Create a service credential

In your work brain’s service credentials, create a read-and-write credential labelled “claude-code-capture” and copy its ck_ key. This lets the hook post to Cortex without a browser.

Then follow the tab for your operating system. Each one creates a small script, stores your credential, and registers the hook.

macOS
Linux
Windows

The script uses curl (already on macOS) and jq, a small JSON tool. Install jq once:

brew install jq

1. Save this as .claude/hooks/cortex-capture.sh:

#!/usr/bin/env bash
# Cortex capture hook for Claude Code (SessionEnd). Posts the finished session's log to Cortex,
# which cleans it to the conversation contract (docs/conversation-contract.md) and files it.
#
# Needs: curl and jq. Env: CORTEX_TOKEN (a ck_ service credential, Write, on the brain that should
# receive sessions); optional CORTEX_API (default https://api.oncortex.ai) and CORTEX_BRAIN (a brain
# slug or id; only needed with a token that can write more than one brain).
#
# The session id is the source reference's item id, so a resumed session's later post is linked
# as a revision of the earlier one; the line count is its version. The body is streamed through a
# pipe, never passed as an argument (a large session would exceed the shell's argument limit), and
# the hook never fails the session end.
set -uo pipefail

input=$(cat)
transcript_path=$(printf '%s' "$input" | jq -r '.transcript_path // empty')
session_id=$(printf '%s' "$input" | jq -r '.session_id // empty')
[ -n "$transcript_path" ] && [ -f "$transcript_path" ] && [ -n "$session_id" ] || exit 0
[ -n "${CORTEX_TOKEN:-}" ] || exit 0

lines=$(wc -l < "$transcript_path" | tr -d ' ')
api="${CORTEX_API:-https://api.oncortex.ai}"
query=""
[ -n "${CORTEX_BRAIN:-}" ] && query="?brain=${CORTEX_BRAIN}"

jq -n \
  --arg filename "claude-code-$session_id.jsonl" \
  --arg sid "$session_id" \
  --arg version "$lines" \
  --rawfile content "$transcript_path" \
  '{filename: $filename, content: $content, provider: "claude-code", providerItemId: $sid, version: $version}' \
| curl -s --max-time 120 "$api/api/v1/inbox$query" \
    -H "Authorization: Bearer $CORTEX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- > /dev/null || true
exit 0

Make it runnable:

chmod +x .claude/hooks/cortex-capture.sh

2. Store your credential in .claude/settings.local.json (kept out of shared files):

{
  "env": { "CORTEX_TOKEN": "ck_your_key_here" }
}

3. Register the hook in .claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/cortex-capture.sh"
          }
        ]
      }
    ]
  }
}

The script uses curl and jq, a small JSON tool. Install jq once with your package manager:

sudo apt install jq    # Debian / Ubuntu
sudo dnf install jq    # Fedora

1. Save this as .claude/hooks/cortex-capture.sh:

#!/usr/bin/env bash
# Cortex capture hook for Claude Code (SessionEnd). Posts the finished session's log to Cortex,
# which cleans it to the conversation contract (docs/conversation-contract.md) and files it.
#
# Needs: curl and jq. Env: CORTEX_TOKEN (a ck_ service credential, Write, on the brain that should
# receive sessions); optional CORTEX_API (default https://api.oncortex.ai) and CORTEX_BRAIN (a brain
# slug or id; only needed with a token that can write more than one brain).
#
# The session id is the source reference's item id, so a resumed session's later post is linked
# as a revision of the earlier one; the line count is its version. The body is streamed through a
# pipe, never passed as an argument (a large session would exceed the shell's argument limit), and
# the hook never fails the session end.
set -uo pipefail

input=$(cat)
transcript_path=$(printf '%s' "$input" | jq -r '.transcript_path // empty')
session_id=$(printf '%s' "$input" | jq -r '.session_id // empty')
[ -n "$transcript_path" ] && [ -f "$transcript_path" ] && [ -n "$session_id" ] || exit 0
[ -n "${CORTEX_TOKEN:-}" ] || exit 0

lines=$(wc -l < "$transcript_path" | tr -d ' ')
api="${CORTEX_API:-https://api.oncortex.ai}"
query=""
[ -n "${CORTEX_BRAIN:-}" ] && query="?brain=${CORTEX_BRAIN}"

jq -n \
  --arg filename "claude-code-$session_id.jsonl" \
  --arg sid "$session_id" \
  --arg version "$lines" \
  --rawfile content "$transcript_path" \
  '{filename: $filename, content: $content, provider: "claude-code", providerItemId: $sid, version: $version}' \
| curl -s --max-time 120 "$api/api/v1/inbox$query" \
    -H "Authorization: Bearer $CORTEX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- > /dev/null || true
exit 0

Make it runnable:

chmod +x .claude/hooks/cortex-capture.sh

2. Store your credential in .claude/settings.local.json (kept out of shared files):

{
  "env": { "CORTEX_TOKEN": "ck_your_key_here" }
}

3. Register the hook in .claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/cortex-capture.sh"
          }
        ]
      }
    ]
  }
}

Windows uses PowerShell, which is built in, so there is nothing extra to install. Claude Code runs the hook without any change to your execution policy.1. Save this as .claude/hooks/cortex-capture.ps1:

# Cortex capture hook for Claude Code on Windows (SessionEnd). Posts the finished session's log to
# Cortex, which cleans it to the conversation contract (docs/conversation-contract.md) and files it.
# Env: CORTEX_TOKEN (a ck_ service credential, Write); optional CORTEX_API and CORTEX_BRAIN.
# The session id is the source reference's item id, so a resumed session's later post is linked as
# a revision; the line count is its version. The hook never fails the session end.
try {
    $data = [Console]::In.ReadToEnd() | ConvertFrom-Json
    if (-not $env:CORTEX_TOKEN -or -not $data.transcript_path -or -not (Test-Path $data.transcript_path)) { exit 0 }

    $api = if ($env:CORTEX_API) { $env:CORTEX_API } else { "https://api.oncortex.ai" }
    $query = if ($env:CORTEX_BRAIN) { "?brain=$($env:CORTEX_BRAIN)" } else { "" }
    $content = [System.IO.File]::ReadAllText($data.transcript_path)
    $lines = [System.IO.File]::ReadAllLines($data.transcript_path).Length

    $body = @{
      filename       = "claude-code-$($data.session_id).jsonl"
      content        = $content
      provider       = "claude-code"
      providerItemId = "$($data.session_id)"
      version        = "$lines"
    } | ConvertTo-Json -Depth 3

    Invoke-RestMethod -Uri "$api/api/v1/inbox$query" -Method Post `
      -Headers @{ Authorization = "Bearer $($env:CORTEX_TOKEN)" } `
      -ContentType "application/json; charset=utf-8" `
      -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) -TimeoutSec 120 | Out-Null
} catch { }
exit 0

2. Store your credential in .claude/settings.local.json (kept out of shared files):

{
  "env": { "CORTEX_TOKEN": "ck_your_key_here" }
}

3. Register the hook in .claude/settings.json. The "shell": "powershell" line is what tells Claude Code to run the .ps1 script:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/cortex-capture.ps1",
            "shell": "powershell"
          }
        ]
      }
    ]
  }
}

Use forward slashes in the path even on Windows; Claude Code converts them. Needs PowerShell 5.1 or newer, which ships with Windows 10 and 11.

To capture sessions across every project rather than just the current one, put the same hook in your user-level ~/.claude/settings.json and use the script’s full path. From then on, each session lands in your personal inbox through the same door as any other item, and Cortex cleans it first. A raw session log is mostly the output of the commands and tools the agent ran; the conversation itself is often under 1% of it. Cortex keeps what you typed, what the assistant said and one line for each thing it did (“ran: Show working tree status”, “edited RunnerEngine.cs”), drops the tool output, the assistant’s private reasoning and anything injected behind the scenes, and masks passwords, API keys and tokens. The original log stays on the item. The cleaned session goes straight to the conversation skill, which reads it with a high bar: only a real decision, an idea in your own words, a durable fact about someone or something your brain tracks, or a substantial piece of work gets filed. Most sessions produce nothing, and that is the intended result. If you come back to a session and carry on, the next time it ends Cortex links the new copy to the earlier one as a new version, rather than treating it as a duplicate. Ask your next session “what did we work on last time?” and it can tell you.

If you set this hook up before 2 October 2026, replace the script with the one above. The old one sent the session id as a delivery id, so a session you resumed was turned away as a duplicate the second time it ended, and on very long sessions it could fail to send at all.

Other agents

Any tool that can run a command or call a web address when it finishes can capture the same way: post the conversation to https://api.oncortex.ai/api/v1/inbox with a service credential. The default-inbox address means you never name a brain; it goes to the credential’s brain. Send its own log as it is, with provider set to the tool’s name (copilot-cli, codex, gemini-cli) and providerItemId set to its session id: Cortex reads the common message formats most agents use and cleans the log the same way. A format it cannot read is flagged in your inbox for you to look at, never filed raw.

Keeping it tidy

Captured conversations are filed by the conversation skill, which pulls out the substance rather than dumping raw transcripts, and files nothing when a session held nothing durable. If two sessions capture the same thing, duplicate handling stops your brain filling up with repeats.

Checking the hook is still working

A hook stops quietly when a laptop is rebuilt or a credential expires. Ask your agent to run the health check on the brain: it reports when the last transcript arrived and when the claude-code-capture credential was last used, and says what to do if either has gone stale. See brain health.

Getting Started

Brains

How Information Gets In

Filing and Recall

Connecting Your AI

Teams

Account and Security

Reference

Capturing agent conversations

The easy way: just ask

The automatic way: a session hook (advanced)

Other agents

Keeping it tidy

Checking the hook is still working

​The easy way: just ask

​The automatic way: a session hook (advanced)

​Other agents

​Keeping it tidy

​Checking the hook is still working

The easy way: just ask

The automatic way: a session hook (advanced)

Other agents

Keeping it tidy

Checking the hook is still working