Hooks and recovery

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

Activation

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

In supported Codex clients, open /hooks. Review and trust the intended Memford hook. Project hooks also require a trusted project. Changed definitions need another review. Check the startup matcher and enabled state.

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

Invalid output

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.

Verification

Finish the MCP save/read check and retain the unique setup note’s ID and text.
Start a fresh session in the selected project using the existing authorization.
Observe a successful startup hook and a read of that project. Confirm the setup note reached the agent before a manual Memford call.

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.

Manual

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.

Checkpoints and abrupt exits

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 three hooks: SessionStart, 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. Each client has its own private queue. The installer does not add a periodic timer or promise that a hard exit runs a hook.

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.

Install the terminal adapter

First finish the normal MCP setup and verify the selected project. This optional helper currently requires a separate project key in an owner-only local JSON file containing token. It 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. 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.

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.

Stage selected progress

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

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. The adapter generates a checkpoint ID when none is supplied. Retain that returned ID for an exact 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.

Confirm a handover

Stage the current selected facts, then run:

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.

Recover a pending checkpoint

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.

Verification scope

The native Codex path has demonstrated fresh startup, a real Stop-hook save/readback and fresh-session recovery after hard termination. The published Cloudflare helper has also passed save/readback and startup checks. The Claude Code adapter is implemented, but its equivalent native end-to-end session test remains outstanding. 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.

Hosted agents

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.