Integrations

Harness Capture

Understand and operate Basic Memory lifecycle hooks for Claude Code and Codex.

Basic Memory plugins for Claude Code and Codex use bm hook as one shared lifecycle front door. Plugin hook scripts only pass the harness event into Basic Memory; context recall, checkpoint coordination, capture, retention, and health reporting live in the installed Basic Memory package.

Understand the lifecycle events

Command	Harness event	What Basic Memory does
`bm hook session-start`	SessionStart	Reads configured projects, prints a bounded context brief, and captures a `session_started` envelope when capture is enabled. After Codex compaction, it can also request an agent-authored checkpoint.
`bm hook pre-compact`	PreCompact	Captures a `compaction_imminent` envelope. Claude can write a durable checkpoint from its transcript; Codex defers the checkpoint request to the post-compaction SessionStart because Codex ignores PreCompact output.
`bm hook stop`	Retired Stop hook	Returns a continue response so stale pre-upgrade Codex hook entries do not block a session. New installs do not register it.

Active lifecycle commands are fail-open: a capture or recall error is reported without interrupting the agent session.

Use plugin-managed hooks

The Basic Memory Claude Code and Codex plugins register SessionStart and PreCompact automatically. Their status workflows also surface the shared local inbox, pending and archived counts, last flush, resolved project mapping, capture state, checkpoint state, Basic Memory version, and uv version.

Run the core status command directly when you need the underlying evidence:

bm hook status --harness codex --project-dir /path/to/repository

bm hook status --harness claude --project-dir /path/to/repository

The plugin's bm-status workflow includes this hook health in its broader Basic Memory configuration and reachability report.

Install hooks without a plugin

Standalone users can add the same user-level hooks directly:

bm hook install --harness codex
bm hook install --harness claude

Install is idempotent. It adds ownership-tagged entries to ~/.codex/hooks.json or ~/.claude/settings.json and preserves unrelated user hooks and settings.

Remove only the entries Basic Memory installed:

bm hook remove --harness codex
bm hook remove --harness claude

The plugin and standalone flows use the same runtime behavior. Do not manually register both for one harness.

For development against a nonstandard Basic Memory executable, BM_BIN overrides the uv-managed command used by plugin hook shims.

Control local event capture

Lifecycle capture is enabled by default. Each event appends one bounded JSON envelope to the owner-private local WAL at the Basic Memory data directory's inbox/ path, normally ~/.basic-memory/inbox/. The envelope contains lifecycle metadata such as the event, session, working directory, project hint, and model; it is not a transcript or a knowledge-graph note.

Set captureEvents to the JSON boolean false to opt out:

{
  "basicMemory": {
    "captureEvents": false
  }
}

{
  "basicMemory": {
    "captureEvents": false
  }
}

Malformed capture settings fail closed: Basic Memory disables capture rather than guessing that an invalid value means true.

Flush and retain envelopes

Archive pending envelopes locally:

bm hook flush
bm hook flush --older-than-days 30

Flush moves valid envelopes into inbox/processed/, deduplicates replays, leaves unresolved pending work visible, and prunes processed or unresolved-pending envelopes older than the retention window. It never writes graph notes or sends the lifecycle trace to a team project.

Use bm hook status after flushing to confirm the pending count, archived count, and last-flush timestamp.

Claude Code — connect Claude Code to Basic Memory.
OpenAI Codex — connect the Codex app or CLI.
CLI Reference — exact bm hook command reference.

Edit this pageorReport an issue

Agent Skills

Pre-built skills that teach AI agents how to use Basic Memory effectively.

Code Project Documentation