Skip to content

Opt-in zero-token import hooks

These recipes upload completed conversation artifacts without asking a model to read, parse, or summarize them. The HTTP transport itself therefore consumes zero additional model tokens. The surrounding agent session still has its normal token use.

Nothing is enabled by default. Start with the manual command, then install only the lifecycle hooks you want. The recipes were checked on 2026-10-29 with Codex CLI 0.152.0, Claude Code 2.1.288, OpenCode 1.19.0, and Gemini CLI 0.57.0. Hook formats and export commands are upstream compatibility contracts; recheck this page after upgrading a client.

Shared uploader

All four recipes call tools/import_to_memory.py. Set the hub connection in the shell or service environment that starts the client; do not put the bearer token in a hook command or a repository file:

export MEMORY_HUB_URL=http://127.0.0.1:8000
export MEMORY_API_TOKEN='<memory:write bearer token>'

Run a manual smoke check with a completed export:

python3 /absolute/path/to/ai-memory-hub/tools/import_to_memory.py \
  <PARSER> /absolute/path/to/completed-export.json

The uploader (including client-specific adapters that delegate to it):

  • accepts only regular, non-empty files up to 20 MB;
  • normally refuses files modified in the last five seconds;
  • copies to a private temporary snapshot and refuses the upload if the source changes while copied;
  • deletes the snapshot after success or failure;
  • never prints the token, request body, conversation text, or full server response; and
  • prints at most 100 bounded result receipts. Repeated runs use the hub's normal hash deduplication and report deduplicated: true where applicable.

Missing and ephemeral sessions fail locally because no file exists. An active or still-changing file is refused. --min-age-seconds 0 is reserved for synchronous client end hooks that provide a closed transcript path; it still uses and checks the snapshot.

Codex CLI and app

Codex SessionEnd supplies transcript_path on standard input and runs synchronously after the main task ends. Add this entry to the user-level ~/.codex/hooks.json file, merging it with any existing hooks object:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /absolute/path/to/ai-memory-hub/tools/import_to_memory.py codex-rollout-jsonl --hook-json-field transcript_path --min-age-seconds 0",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

This imports the path provided by Codex; it does not search for the newest file. Ephemeral tasks without a persisted rollout are skipped with a bounded error. Remove the SessionEnd entry (or the whole file if it contains nothing else) to disable the automation. Codex requires review/trust before running a new non-managed hook. See the upstream Codex hooks reference.

Claude Code

Claude Code SessionEnd supplies the closed session's transcript_path on standard input. Add this entry to ~/.claude/settings.json, merging it with any existing settings and hooks:

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /absolute/path/to/ai-memory-hub/tools/import_to_memory.py claude-code-session-jsonl --hook-json-field transcript_path --min-age-seconds 0",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Only top-level session transcripts should be imported; do not point the command at files under a subagents directory. Remove this SessionEnd entry to disable it. The hook is intentionally installed at user scope so an untrusted repository cannot replace the command. See the upstream Claude Code hooks reference.

OpenCode

Do not upload on session.idle: an idle session can be resumed, so its export is not a closed-session boundary. Use this explicit post-session command after leaving the session. It creates a sanitized, self-contained export and uploads that snapshot:

import-opencode-session() (
  session_id=${1:?Usage: import-opencode-session SESSION_ID}
  artifact=$(mktemp "${TMPDIR:-/tmp}/opencode-session.XXXXXX")
  trap 'rm -f "$artifact"' EXIT HUP INT TERM
  opencode session export "$session_id" --sanitize >"$artifact"
  python3 /absolute/path/to/ai-memory-hub/tools/import_to_memory.py \
    opencode-session-json "$artifact" --min-age-seconds 0
)

Find the ID with opencode session list, exit that session, then run import-opencode-session <SESSION_ID>. Remove the shell function from your profile to disable it. No background watcher or project plugin is installed. See the upstream OpenCode session commands.

Gemini CLI

Gemini's SessionEnd hook is best-effort and does not provide an exported artifact path, so use an explicit export and upload. Inside the completed Gemini session, create a supported export:

/chat share /absolute/path/to/gemini-session.json

After leaving the session, upload that immutable export:

python3 /absolute/path/to/ai-memory-hub/tools/import_to_memory.py \
  gemini-cli-session-json /absolute/path/to/gemini-session.json --min-age-seconds 0

Older Gemini releases may use /export-session instead of /chat share. Delete the exported file when it is no longer needed. There is no persistent automation to disable in this recipe. See the upstream Gemini CLI hooks reference.

DeepSeek Harness

This explicit recipe is pinned to the documented DeepSeek Harness session-log export contract and the canonical session formats 0 through 4. In the Harness web interface, finish the session, choose Download session log from the Session Header menu (or enter /export), and wait for the dsh-session-<SESSION_ID>.zip download to complete. Then run:

python3 /absolute/path/to/ai-memory-hub/tools/import_deepseek_harness_export.py \
  /absolute/path/to/dsh-session-<SESSION_ID>.zip

The adapter refuses archives modified in the last five seconds, then validates entry count and compressed/uncompressed sizes before extracting into a private temporary directory. It rejects path traversal, absolute paths, duplicate names, encrypted entries, links, devices, malformed ZIPs, oversized members, and more than one root session.jsonl or session.vN.jsonl. Attachments are validated but not extracted. The selected immutable root is delegated to the shared uploader with parser deepseek-harness-session-jsonl and --min-age-seconds 0; the existing importer remains responsible for parsing and supported-version validation.

Sessions below subagents/ are separate conversations and are never merged or uploaded automatically. To import one intentionally, name its exact archive member in a separate run:

python3 /absolute/path/to/ai-memory-hub/tools/import_deepseek_harness_export.py \
  /absolute/path/to/dsh-session-<SESSION_ID>.zip \
  --member subagents/<SUBAGENT_ID>/session.v4.jsonl

The temporary directory is removed after success or failure. Retrying the same root or descendant is safe because hub ingestion deduplicates it, and only the shared uploader's bounded receipt is printed. There is nothing persistent to disable or remove: the adapter is an opt-in manual command. Keep MEMORY_HUB_URL and MEMORY_API_TOKEN only in the command environment.

See the upstream DeepSeek Harness export documentation.

Hermes Agent

This explicit export-and-upload recipe was checked with Hermes Agent 0.22.5. Hermes stores current sessions in ~/.hermes/state.db; never copy that database, its -wal file, or its -shm file. Exit or otherwise end the intended session, find its ID with hermes sessions list, then run:

python3 /absolute/path/to/ai-memory-hub/tools/import_hermes_session.py \
  --session-id <SESSION_ID>

Add --redact to ask Hermes to scrub recognized API keys, tokens, and credentials from the exported copy before upload. For an explicit batch of ended sessions, use an upstream ended-session age filter instead of an unfiltered database export:

python3 /absolute/path/to/ai-memory-hub/tools/import_hermes_session.py \
  --ended-older-than 2d --redact

The adapter creates a private temporary directory, installs cleanup before it runs hermes sessions export, and deletes the JSONL after success or failure. It invokes only the supported Hermes export command, suppresses its output, and then delegates the immutable artifact to the shared uploader with parser hermes-session-jsonl and --min-age-seconds 0. The existing importer retains single- and multi-session boundaries. Missing or invalid IDs, failed or empty exports, files over 20 MB, invalid envelopes, and network failures are refused without printing export content or credentials. Safe retries use normal hub deduplication and emit only the uploader's bounded receipt.

There is nothing persistent to disable or remove: both forms are opt-in manual commands. Keep MEMORY_HUB_URL and MEMORY_API_TOKEN only in the command environment. See the upstream Hermes session guide.

OpenClaw

This safety boundary was checked against OpenClaw 2026.10.7. Current OpenClaw stores session rows and transcripts in per-agent SQLite databases. Its supported backup commands create verified database snapshots, and its public transcript JSONL export is not the legacy Pi-family version 3 tree accepted by pi-session-jsonl. Do not upload or copy a live .sqlite, .db, WAL, SHM, or journal file, and do not reinterpret a current transcript export as a legacy tree. Supporting that newer envelope requires a separately scoped importer.

For an older OpenClaw installation, or a coordinated third-party export that already produces a closed, compatible version 3 JSONL tree, select the intended session explicitly, close the writer, wait at least five seconds, and run:

python3 /absolute/path/to/ai-memory-hub/tools/import_openclaw_session.py \
  /absolute/path/to/closed-openclaw-session.jsonl

The adapter requires one absolute .jsonl path, refuses symbolic links and database/sidecar filenames, and checks only the bounded session header before delegating to the shared uploader with parser pi-session-jsonl and source openclaw. It never searches for a newest artifact and does not transform or parse conversation messages. The existing importer remains authoritative for the complete version 3 tree, active-branch reconstruction, and unsupported input rejection. The shared uploader retains recent/changing-file, empty-file, 20 MB, private-snapshot, cleanup, bounded-receipt, and credential protections. Repeated runs use normal hub deduplication.

There is nothing persistent to disable or remove: this is an opt-in manual compatibility command. Keep MEMORY_HUB_URL and MEMORY_API_TOKEN only in the command environment. See the upstream OpenClaw session storage and backup safety guide.

Pi

This explicit recipe was checked with Pi coding agent 0.73.0 and its version 3 JSONL session format. Pi does not provide a verified end event that supplies a closed session path, so this recipe deliberately does not install a watcher or guess which file is newest.

Before leaving the intended Pi session, run /session and copy the exact session file path that Pi reports. Then exit Pi, wait at least five seconds so the shared uploader can reject a file that is still active, and run:

python3 /absolute/path/to/ai-memory-hub/tools/import_pi_session.py \
  /absolute/path/reported-by-pi/completed-session.jsonl

The adapter accepts only an explicit absolute .jsonl path and delegates it to the shared uploader with parser pi-session-jsonl and source pi. It does not read or reconstruct the conversation. The existing hub importer validates the version 3 tree and reconstructs its active branch. Missing and ephemeral sessions, recent or changing files, files over 20 MB, and invalid session trees are refused by the adapter, uploader, or importer. Retrying the same completed session is safe because normal hub ingestion deduplicates it.

Do not run the command while Pi still has the session open, use it for Oh My Pi or OpenClaw artifacts, or replace the reported path with a newest-file search. There is nothing persistent to disable or remove: this is an opt-in manual command. Keep MEMORY_HUB_URL and MEMORY_API_TOKEN only in the command environment, as described above.

See Pi's upstream session documentation and versioned session format.

Failure handling

The command exits nonzero for missing credentials, missing or unsafe files, network failures, authentication errors, unsupported parser input, and partial or invalid server responses. Hook failures do not expose conversation content or the bearer token. A failed upload can be retried after closing/exporting again; successful retries are safe because hub ingestion is deduplicated.