ContextDB-Codex

<div align="center">
  <img src="assets/contextdb-memory-hero.svg" alt="ContextDB Memory for Codex — Give every task a past" width="100%" />

  <br />

  [![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-718cff.svg)](LICENSE)
  [![Windows x86-64](https://img.shields.io/badge/platform-Windows%20x86--64-36bdd2.svg)](docs/release/support-matrix.md)
  [![0.5.0 alpha](https://img.shields.io/badge/release-0.5.0--alpha.1-bb73ff.svg)](https://github.com/mikhailbovt/ContextDB-Codex/releases/tag/v0.5.0-alpha.1)

  **Automatic project continuity for Codex, backed by a local ContextDB memory graph.**

  [Install](#install) · [See it grow](#how-the-memory-grows) · [Operate safely](#backup-restore-reset-and-uninstall)
</div>

---

Codex can understand a repository brilliantly and still wake up in the next task with the
emotional continuity of a goldfish. ContextDB Memory gives it a durable, local project history:
the decisions already made, constraints that still matter, goals in flight, verified milestones,
and open loops waiting for somebody to stop pretending they do not exist.

The plugin recalls relevant context at the start of substantive work and checkpoints significant
state as the task evolves. It does this through a bundled, listener-free MCP adapter; the database,
runtime, keys, and mutable memory remain on your Windows computer.

> **Release status:** `0.5.0-alpha.1` Windows Developer Preview. The local plugin, automatic hooks,
> typed candidate graph, custody, backup/restore/reset/uninstall flow, and release-bundle verifier
> are implemented and tested. The executable is not code-signed, cross-platform packages are not
> available, and this is not a hosted ContextDB service.

## What it remembers

| Memory kind | Example | Why it survives |
| --- | --- | --- |
| Decision | “Keep the local edition stdio-only.” | Prevents a later task from reopening a settled architecture choice without evidence |
| Constraint | “Do not publish or start containers during this phase.” | Keeps execution inside the project's real boundary |
| Goal | “Prepare both repositories for the first public alpha.” | Lets future work resume against the intended outcome |
| Open loop | “Code signing still needs publisher custody.” | Preserves unfinished work without pretending it is complete |
| Milestone | “Lifecycle suite passed in PowerShell 5.1 and 7.” | Carries forward a verified result with provenance |
| Preference | “Keep internal RFCs local, not public.” | Maintains durable project conventions |
| Fact or evidence summary | “The packaged core has network listeners disabled.” | Gives recall a compact, traceable technical anchor |

Short-lived chatter, guesses, copied logs, secrets, and “maybe someday” noise should not become
durable memory. The active Codex model decides whether a change is significant; the host contract
constrains how it may be written.

## How the memory grows

```mermaid
flowchart LR
    S[Session starts] --> R[Bounded candidate recall]
    R --> W[Codex works with current files]
    W --> C{Durable change?}
    C -- no --> W
    C -- yes --> Q[Quarantined candidate]
    Q --> G[Project / topic / memory DAG]
    G --> R
    Q -. explicit successor .-> Q2[New revision]
```

- `SessionStart` loads the safety and continuity contract for new, resumed, cleared, and compacted
  sessions.
- `UserPromptSubmit` creates at most one bounded recall opportunity when a prompt starts or
  materially changes a substantive workspace task.
- During work and at the loop-safe `Stop` checkpoint, Codex can capture significant decisions,
  constraints, preferences, goals, open loops, and verified milestones automatically—no special
  “remember this” incantation required.
- Stable project, topic, and memory identities make retries converge. A changed fact becomes an
  explicit successor instead of silently overwriting its predecessor.
- Multi-parent links let a memory belong to its project or topic while also connecting to a related
  decision, goal, or open loop.

The hooks create the opportunity and the instructions for automatic memory; they do not turn every
token into immortal sludge. Review the bundled hooks when Codex asks you to trust them, and start a
new task after install or update so the host loads the current package.

## Built to distrust its own memory

Automatic records are typed **candidates**, not canonical truth.

```text
model output → deterministic identity + policy checks → quarantined candidate
                                                     ↛ canonical memory
```

The model-facing MCP surface cannot promote, correct, overwrite, or delete canonical semantic
memory. Before using a candidate, the skill materializes it, traverses its hierarchy, and verifies
that the route reaches the active checkout's project root. Recalled content remains untrusted data:
it is never interpolated into a shell command or treated as authority.

That caution is intentional. Durable hallucinations are just bugs with tenure.

## Architecture

```mermaid
flowchart LR
    subgraph Host[Codex host]
      H[Lifecycle hooks] --> K[ContextDB memory skill]
      K --> M[MCP tools]
    end
    M -->|stdio| P[Local MCP proxy]
    P --> B[Single-owner Windows broker]
    B --> D[(ContextDB native store)]
    D -->|authorized, bounded recall| M
```

The packaged core must report:

```text
build_profile local-mcp
network_listeners disabled
```

The launcher rejects a binary outside that profile. Mutable custody lives outside both the source
checkout and Codex's versioned plugin cache. The plugin does not require a publisher-operated
backend, analytics service, cloud synchronization, or OpenAI API key.

## Install

### From the Codex marketplace

This is the smallest install path. It needs **one public repository**, not a ContextDB source
checkout:

```powershell
codex plugin marketplace add mikhailbovt/ContextDB-Codex --ref v0.5.0-alpha.1
codex plugin add contextdb-memory@contextdb-codex
```

Start a new Codex task after installation. On the first MCP start, the plugin downloads the exact
ContextDB core ZIP pinned by its runtime lock, checks the canonical GitHub Release URL, byte length,
archive SHA-256, safe ZIP layout, executable SHA-256, listener-free build profile, SBOM, notices,
and Rust licenses, then initializes Windows CurrentUser DPAPI custody. Mutable memory is stored
outside the versioned plugin cache.

### From the self-contained release

For an offline installation, download the versioned Windows x86-64 ZIP and its `.sha256` sidecar
from [Releases](https://github.com/mikhailbovt/ContextDB-Codex/releases). Verify the archive against
the sidecar, extract it, and run one command:

```powershell
$archive = (Resolve-Path .\contextdb-codex-0.5.0-alpha.1-windows-x86_64.zip).Path
$expected = ((Get-Content "$archive.sha256" -Raw).Trim() -split '\s+')[0].ToLowerInvariant()
$actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "Release checksum mismatch: $actual" }
Expand-Archive -LiteralPath $archive -DestinationPath .
Set-Location .\contextdb-codex-0.5.0-alpha.1-windows-x86_64
.\install.cmd
```

The release already contains the verified ContextDB executable, dependency notices, CycloneDX
SBOM, Rust runtime licenses, lifecycle scripts, plugin, and public documentation. The installer
runs without downloading a second repository or runtime.

### From source

Clone only this repository for the normal prebuilt path:

```powershell
git clone https://github.com/mikhailbovt/ContextDB-Codex.git
Set-Location ContextDB-Codex
.\scripts\install.ps1
```

The installer downloads and verifies the same pinned core release used by the marketplace path. A
sibling ContextDB checkout is needed only when developing or rebuilding the core yourself:

```powershell
.\scripts\install.ps1 -ContextDbRepo ..\ContextDB
```

Rust `1.97.1` is required only for that optional source-build path.

Verify the installed inventory if needed:

```powershell
codex plugin list --json
```

Start a new Codex task after any installation path so Codex loads the current hooks and skill.

## Verify the implementation

With both repositories available:

```powershell
.\scripts\test-hooks.ps1
.\scripts\test-mcp.ps1
.\scripts\test-auto-hierarchy.ps1
.\scripts\test-custody.ps1 -ContextDbRepo ..\ContextDB
.\scripts\test-lifecycle.ps1 -ContextDbRepo ..\ContextDB
python .\docs\release\validate-publication-kit.py
```

`test-lifecycle.ps1` uses isolated temporary custody and an isolated Codex home to exercise setup,
MCP startup, backup, restore, recoverable reset, marketplace installation, custom-root purge,
runtime purge, and uninstall. The release profile is accepted in Windows PowerShell 5.1 and
PowerShell 7; see the [support matrix](docs/release/support-matrix.md) for the exact evidence
boundary.

## Backup, restore, reset, and uninstall

Back up to a new path outside live custody:

```powershell
.\scripts\backup.ps1 -Destination D:\Backups\contextdb-memory.cdb-backup
```

Restore a verified composite backup:

```powershell
.\scripts\restore.ps1 -Backup D:\Backups\contextdb-memory.cdb-backup
```

Create fresh custody while preserving the old state in a timestamped recovery directory:

```powershell
.\scripts\reset.ps1 -ConfirmReset RESET-CONTEXTDB-MEMORY
```

Remove only the installed plugin:

```powershell
.\scripts\uninstall.ps1
```

Data and immutable runtimes require separate opt-in flags and an exact confirmation token:

```powershell
.\scripts\uninstall.ps1 `
  -RemoveMarketplace `
  -PurgeData `
  -PurgeRuntime `
  -ConfirmPurge DELETE-CONTEXTDB-MEMORY
```

Filesystem removal is not a promise of forensic secure erasure. Backups and host conversation
history remain separate copies.

## Deliberate nonclaims

This preview does not claim deterministic canonical adjudication, forensic hard deletion,
KMS/HSM custody, provider-copy erasure, semantic-scale certification, Authenticode signing,
cross-platform install