Skip to content

Hooks and recovery

Check the hook. Prove the read. Keep your existing instructions intact.

Identify the installed client and version. Inspect its effective startup hooks, including user, project and plugin sources. Preserve existing handlers.

In a supported Codex CLI, open the intended project and use /hooks. Review each Memford command and trust its exact definition for SessionStart, UserPromptSubmit, PostToolUse, Stop and PreCompact. Project hooks also require a trusted project through Codex’s normal project-trust flow. Changed definitions need another review. Check the event matchers and enabled state; keep unrelated handlers intact.

Use the installed version’s official documentation. Other clients have their own activation and output rules. If hooks are unavailable, use manual startup reads.

Hook failed: invalid session start JSON output

Codex invoked the hook but rejected its response. Inspect the handler before testing it. Use synthetic startup input, a timeout and safe diagnostics.

A command hook that retrieves notes must return the client’s event format. For Codex SessionStart, this is a JSON output shape:

{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "Project memory: <bounded retrieved notes>"
}
}

This example only shows the format. A real handler must read the authorized project. Return one valid output; send diagnostics to stderr. Keep raw MCP responses, debug prints and credentials out of the JSON output. Treat retrieved notes as reference data.

  1. Finish the MCP save/read check and retain the unique setup note’s ID and text.
  2. Start a fresh session in the selected project using the existing authorization.
  3. Observe a successful startup hook and a read of that project. Confirm the setup note reached the agent before a manual Memford call.
  4. To verify ongoing refresh, save an authorized project update during work and confirm it reaches the agent at the next supported prompt or tool boundary. If the host provides a file or preview, read the complete attachment before relying on omitted context.

Record these independently: configured, enabled and trusted, output validated, startup retrieval verified. Check whether stored authorization was reused. Report token renewal as untested unless it was exercised.

A hook file, separate SDK test or manual read does not prove startup automation. Do not bypass hook trust. Stop dependent Memford operations if authentication fails.

Keep a project instruction to read the selected project’s relevant notes at the beginning of each session. Preserve existing instructions and use the client’s documented configuration.

Report the limitation explicitly and perform the read when work starts. Manual retrieval keeps the saved knowledge available; it is not verified automatic startup.

The selective checkpoint adapter supports local Codex and Claude Code command hooks on macOS and Linux with Node.js 22 or newer. At startup it includes current active assigned account standards in full alongside a bounded recent-note view. It stages decisions, outcomes, open questions and next steps. It does not capture transcripts or infer facts from every answer.

After your project consent, the installer adds a convention for the agent to stage meaningful changes. It installs SessionStart, UserPromptSubmit, PostToolUse, Stop and PreCompact. Stop and PreCompact upload staged changes and verify exact readback. SessionStart loads current project memory and retries a bounded part of the pending queue. UserPromptSubmit and PostToolUse refresh at supported work boundaries; unchanged PostToolUse views are omitted within that session. Each client has its own private queue. The installer does not add a periodic timer or promise that a hard exit runs a hook.

Updated local installations enable boundary refresh by default. The hooks authenticate and load current notes, full assigned rules, skill summaries and human-approved context before preparing additionalContext for the next suitable model step. They do not read tool arguments or transcripts. Memford tool calls skip the PostToolUse refresh to avoid redundant loops. A failed read returns an explicit failure message and no cached context. The next user prompt and fresh startup always prepare a new view, giving missed output another delivery opportunity. PostToolUse deduplication records prepared output, not a native acknowledgment; it cannot guarantee delivery after every tool action.

This is hook-based pull, not a persistent subscription. The exact native event must be supported, enabled and trusted. Existing installations and credentials keep working; publishing this release does not modify local hooks. Run the updated installer for the same verified binding, preserve existing handlers, and review the changed definitions in the client. Existing version-1 configurations without context_refresh: true retain startup-only behavior.

For hosts with a persistent runtime, the separately published context runtime module exports createContextRefresher(config, client). Call start() with an authenticated, project-scoped MCP client before starting work. It subscribes before reconciliation where supported; provide() performs a fresh authorized reconciliation and returns a bounded replacement view for the host to place in its next model request. Call close() on shutdown and recreate the controller after replacing a connection. Subscription failure falls back to explicit pulls. The host still owns scheduling and context insertion.

The runtime records received, loaded and provided separately. provided means prepared for the host; confirm actual host delivery independently. None proves that the model understood or followed the information. Streamable HTTP alone does not prove a working stream or model integration, and the existing five-second change check is not a real-time SLA.

Native hosts also limit hook output. Claude Code can put large additionalContext in a file with only a preview; Codex applies its configured context limit. A complete prepared payload is therefore not proof that every rule or note reached the model. Inspect the host’s actual output handling and retrieve omitted material through the existing authorized memory tools before dependent work. See Claude context handling and Codex large hook output.

Checkpoints use an immutable retry ID. A lost response can be retried without duplicating the note. If an owner has changed or deactivated an original, its pending checkpoint is retained as blocked; it cannot reverse that change or hold up later checkpoints.

An end hook cannot protect unsaved work during a crash or power loss. Recovery starts from the last confirmed remote checkpoint. Pending local knowledge needs the original computer and a working connection before other computers can read it.

First finish the normal MCP setup and verify the selected project. This optional helper requires a project key in an owner-only local JSON file containing token. Reuse an existing valid key file for that project when available; otherwise create a project key in Agents → Connections. The helper does not reuse the native client’s OAuth credential store. Never put the key in chat or command arguments.

Download and inspect the actual installer and adapter, saved beside each other in a permanent local folder. SHA-256 checksums identify the published files, including the separate context runtime module for host integrations. These are standalone Node.js scripts, not an npm package.

Run the installer with your verified values. The credential path identifies a private file, never the credential itself.

Terminal window
node /absolute/path/memory-install.mjs \
--root /absolute/project/path \
--client codex \
--project-id '<verified-project-id>' \
--endpoint https://memford.ai/mcp \
--credential-file /absolute/private/project-key.json \
--consent-checkpoints

Use --client claude for Claude Code. An optional --client-name gives this adapter a useful source label, such as “Codex · Work laptop”; use a separate project key to give the computer a distinct authenticated identity. Existing hooks and instructions are preserved. Another project requires an explicit new binding; the installer refuses to silently replace one. Keep the permanent adapter folder in place. Review and activate the exact hooks in the native client, then follow Verification. Installing files is not activation.

The managed project instructions tell the agent how to stage selected JSON. A handover flush returns confirmed note IDs and fails if saving or exact readback is incomplete. Local state is private and excluded from Git. Known credential patterns are rejected, but that check cannot replace careful selection of what to store.

  1. Check the existing .memory/codex/config.json or .memory/claude/config.json for the verified project ID, endpoint, credential-file path and runtime path. Keep the credential contents private.
  2. Download and inspect the current installer and adapter at the links above. Update them in the existing permanent adapter folder, then rerun the installation command with the same project root, client, project ID, endpoint and credential-file path. Preserve any existing client-name label. The installer enables context_refresh: true and adds missing events while preserving other handlers and project instructions.
  3. Review the resulting .codex/hooks.json or .claude/settings.local.json in the native client. Codex uses the normal /hooks review. Confirm all five events are enabled and trusted. Keep one Memford handler per event for this binding; if the executable or adapter path changed, explicitly review and remove only the superseded Memford handler to avoid duplicate execution.
  4. Start a fresh native session and repeat Verification, including an update during ongoing work.

The installer refuses a conflicting project, endpoint or credential-file binding. Resolve the intended binding instead of deleting private state to force an update. Existing queues retain their original checkpoint IDs and expected revisions; upgrading does not turn older unversioned checkpoints into protected writes.

With checkpoint consent already granted, the agent sends a concise selected update to the installed adapter. For example, using the verified paths from installation:

Terminal window
node /absolute/path/memory-lifecycle.mjs stage \
/absolute/project/path/.memory/codex/config.json <<'JSON'
{
"decisions": ["Use TypeScript for shared modules."],
"outcomes": ["The targeted tests passed."],
"open_questions": ["Verify the same setup in the second client."],
"next_steps": ["Start a fresh session and check the saved decision."]
}
JSON

Use only facts that actually happened. Each array is optional, with at least one nonempty selected item in the update. For a new protected checkpoint, add expected_memory_revision using the exact revision of the context considered when deriving this contribution. Do not fetch a newer revision just to label old work. Omitting it remains compatible with existing queues but leaves the context version check explicitly unverified.

Memford compares the supplied revision and appends the note atomically. A checked receipt confirms the basis of that original append. It does not prove that the model understood the context or protect external file changes and tool actions. Exact save/readback verification and the context version check are separate results; a legacy write can be saved successfully without a checked context version.

The adapter generates a checkpoint ID when none is supplied. Retain that returned ID with the exact fields and expected revision for an uncertain-success retry; a new meaningful update gets a new ID. A successful stage can mean queued locally, not saved remotely. Stop or PreCompact flushes pending updates; you can also flush deliberately. If the service rejects a stale basis, the adapter moves that unchanged checkpoint to blocked state and continues other eligible items. Read current context, reconsider the work and explicitly stage a new reviewed checkpoint. It never silently relabels the old contribution.

Stage the current selected facts, then run:

Terminal window
node /absolute/path/memory-lifecycle.mjs flush \
/absolute/project/path/.memory/codex/config.json

The result must report verified: true, confirmed note IDs, no pending items and no blocked items before you claim that this handover was saved and read back. The command fails when that verification is incomplete. An empty queue reports no newly staged checkpoint; it does not claim a new handover was saved.

Return the verified project ID and its project-specific setup brief for the next client, without credentials. Each new client must authorize that same project independently. A general service-generated handover document or machine-readable transfer package is not yet available.

If a connection fails, selected progress remains in that computer’s private pending queue. Restore the connection and retry delivery from that computer. Another computer can read only what was confirmed remotely.

An item whose original was later edited, deactivated or deleted may become blocked, because exact active readback no longer matches it. Inspect its saved receipt and current note before deciding what new knowledge to stage. Do not reactivate the original or change its retry payload to force success. Later valid checkpoints can still be delivered.

The native Codex path has demonstrated fresh startup, a real Stop-hook save/readback and fresh-session recovery after hard termination. On 18 October 2026, an updated native Codex session also received a new project note after a running tool completed and used its previously unknown ID, revision and exact fact. The host’s full context attachment, including the assigned standard, was explicitly read; automatic reading of every large attachment and general model compliance are not established. A separate fresh session confirmed a protected checkpoint saved by the native Stop hook. The published Cloudflare helper has also passed save/readback and startup checks.

In isolated native Claude Code sessions, SessionStart delivered project memory, Stop saved a staged checkpoint with exact readback, and a fresh SessionStart retrieved that checkpoint. Those hook checks used the adapter’s separate project key. Native Claude Code PreCompact and recovery after hard termination remain unverified. A previously failing Perstat hook is not repaired merely by publishing this helper.

On every new computer or client version, repeat the native verification. Use either project hooks or an equivalent local plugin for one client, not both, to avoid duplicate hook execution. The plugin assets are not a published marketplace installation.

OpenAI Dots can use supported account plugins. Automatic cloud lifecycle hooks require enterprise managed configuration; this local command adapter does not run inside a personal cloud Dot. Grok Bot documents remote HTTPS MCP with individual OAuth, but a general Bot start/stop hook contract has not been verified. Grok Build hooks are a separate product.

Use Memford’s project-scoped MCP connection for deliberate reads and writes in these hosted clients. Verify each connection before reporting compatibility; access alone is not proof of automatic capture or recovery.

The current startup adapter includes assigned skill summaries and the product capability revision returned by Memford. It does not fetch complete skills or execute a feature guide. Agents load a relevant skill immediately before applying it and consult the capability manifest when the revision changes. Existing installed adapters need a reviewed update; publication of a new guide does not update them automatically.

Centrally managed skills work through the authenticated MCP connection without local skill files or these checkpoint hooks. The server supplies project-scoped metadata and retrieval guidance; ask your agent to list or apply an assigned Memford skill. Automatic agent selection and hook execution are separate client behaviors and must be verified independently.