# codex-substrate-memory

Native OpenAI Codex plugin for durable Substrate memory: hosted sign-in, automatic canonical recall, lifecycle capture, explicit wiki tools, and optional prior-history import.

**Requires Codex CLI 0.147.0+ and Python 3.11+ available as `python3` (`python3.exe` on Windows).** Codex 0.133.0 does not provide `SessionEnd`.

## Install

The release marketplace is the normal installation surface once a release is published. For a source checkout:

```console
codex plugin marketplace add Substrate-memory/codex-substrate-memory --ref v0.2.0
codex plugin add codex-substrate-memory@substrate-memory
```

Start a new Codex session. Open `/hooks`, review the exact six packaged commands, and trust them. Installation never bypasses Codex hook trust.

No TOML editing, pasted API key, or global `notify` replacement is required. Codex gives hooks an owner-private data root; the bundled MCP launcher resolves the same installed per-plugin root without exposing it to the model or user configuration.

## Connect

Ask Codex to use `substrate_setup` with `action: begin`. Open the returned complete authorization URL and approve the one-time code yourself. `substrate_setup` with `action: poll` completes the connection. The hosted credential is held in the OS secret service when available, otherwise an owner-private fail-closed file—not TOML, argv, tool output, or logs.

Prior-history import is a separate decision. `substrate_history_consent` can decline or return instructions, but model/MCP calls cannot approve. Approval requires running the plugin's `history-consent` command in a direct interactive terminal and typing the displayed phrase. Declining does not disable future capture or recall. Approval imports interactive root Codex/VS Code threads through documented `codex app-server` read APIs; it does not scrape rollout JSONL, hidden reasoning, or subagent threads.

## Tools

| Tool | Purpose |
|---|---|
| `substrate_search` | Search canonical entity-quality-v2 memory cards. |
| `substrate_wiki_search` | Search all permitted published wiki pages. |
| `substrate_read` | Read one published wiki page. |
| `substrate_query` | Ask a cited question over published memory. |
| `substrate_ingest` | Submit source text for asynchronous ingestion. |
| `substrate_job_status` | Check an asynchronous ingestion job. |
| `substrate_remember` | Durably admit a fact/decision and report queued, delivered, or rejected truthfully. |
| `substrate_sync` | Request a queue drain and report actual delivery state. |
| `substrate_status` | Show content-free connection, queue, and import status. |
| `substrate_setup` | Begin, poll, inspect, or repair hosted sign-in. |
| `substrate_history_consent` | Decline history import or request direct human-approval instructions. |

## Capture and recall

Packaged adapters consume documented `SessionStart`, `UserPromptSubmit`, `PostToolUse`, `Stop`, `PreCompact`, and `SessionEnd` JSON. They never read `transcript_path`.

- `UserPromptSubmit`: durably admits the visible user prompt, then may add bounded cited recall.
- `PostToolUse`: durably admits bounded visible tool input/results.
- `Stop`: durably admits only `last_assistant_message`.
- `PreCompact` / `SessionEnd`: content-free boundaries only.
- `SessionStart`: lineage/start boundary only.

Hooks perform no delivery retries. A long-lived MCP worker drains the private SQLite WAL queue with transactional multiprocess claims, deterministic idempotency keys, and bounded retry backoff. Capture failure never blocks ordinary Codex use.

Automatic recall fails closed unless the server advertises `stream-v2`, `entity-wiki-v1`, and `entity-quality-v2` with canonical redirects/cards. Returned items must be canonical immutable entity paths and quality version 2. Explicit wiki search remains a separate surface.

## Privacy and durability

- Fixed origin: `https://app.trysubstrate.co`; redirects are rejected.
- Credentials and configured secrets are redacted before persistence.
- State, queue, credentials, and import checkpoints reject symlinks and require private storage.
- Hook state/checkpoints store only identifiers, counters, digests, acknowledgements, and content-free errors.
- History discovery is bounded to 10,000 interactive root threads; each thread is bounded to 1,000 visible messages / 2,000,000 serialized characters.
- Redaction cannot prove arbitrary sensitive prose absent. Visible content is sent to the trusted hosted Substrate service after redaction.

## Legacy compatibility

`substrate-codex configure`, the global `notify` adapter, and `sweep-rollouts` remain non-default migration aids. `configure --write` is retired and never changes `config.toml`. Native packaging never replaces an existing global notify hook.

## Development and verification

```console
python -m pip install -e '.[dev]'
python -m ruff check .
python -m pytest -q
python -m compileall -q src scripts
python scripts/verify_public_plugin_candidate.py --root .
CODEX_PLUGIN_SOURCE_COMMIT="$(git rev-parse HEAD)" python scripts/build_plugin.py --check
```

See `docs/architecture.md`, `docs/operation.md`, `docs/threat-model.md`, and `docs/releasing.md`. Publication/deployment and live-production certification are separate actions; this repository does not claim permission enforcement or connected-system actions.

## License

MIT © 2026 Sightline Technologies Inc.