ContextDB Memory README

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

Install · See it grow · Operate safely

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 own Windows or Linux computer.

Release status: 0.6.0-alpha.3 Developer Preview for Windows x86-64 and Linux x86-64. Both local profiles include automatic hooks, a typed candidate graph, platform-specific custody, recovery and uninstall controls, and independently verifiable release bundles. Executables are unsigned, macOS and ARM64 are not supported, and this is not a hosted ContextDB service. The Linux ELF uses an Ubuntu 22.04 / glibc 2.35 baseline; other glibc-based x86-64 distributions require glibc 2.35 or newer and are not individually certified.

What it remembers

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

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.

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

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 local broker]
    B --> D[(ContextDB native store)]
    D -->|authorized, bounded recall| M

The packaged core must report:

build_profile local-mcp
network_listeners disabled

The launcher rejects a binary outside that profile. Windows uses an authenticated named-pipe broker and CurrentUser DPAPI custody; Linux uses an authenticated owner-only Unix-domain socket, 0700 directories, 0600 key and state-head files, and the XDG data hierarchy. Linux file permissions are not transparent encryption: use your operating system's disk encryption when that stronger at-rest boundary matters. Mutable custody lives outside both the source checkout and Codex's versioned plugin cache. Neither profile requires 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. Before adding it, verify that node --version reports v18 or newer; Linux also needs python3 --version to report 3.10 or newer. The repository installers perform these checks automatically, while a raw marketplace add cannot run code before Codex caches the plugin.

codex plugin marketplace add mikhailbovt/ContextDB-Codex --ref v0.6.0-alpha.3
codex plugin add contextdb-memory@contextdb-codex

Start a new Codex task after installation. On the first MCP start, the plugin detects its host OS, downloads the exact ContextDB core ZIP pinned by the matching platform lock, and checks its canonical GitHub Release URL, byte length, archive SHA-256, safe ZIP layout, executable SHA-256, listener-free build profile, target-specific SBOM, dependency notices, and Rust licenses. It then initializes Windows CurrentUser DPAPI custody or Linux owner-only local custody. Mutable memory is stored outside the versioned plugin cache. Both platforms require an x64 build of Node.js 18+ on PATH for the marketplace MCP dispatcher; Linux additionally requires Python 3.10+ but not PowerShell. Neither platform requires a ContextDB checkout, Docker, or a remote MCP service.

From the self-contained release

Each platform has one complete release ZIP; there is no second repository or runtime download. Choose your operating system from Releases, verify the matching .sha256 sidecar, and install it locally.

Linux x86-64:

archive=contextdb-codex-0.6.0-alpha.3-linux-x86_64.zip
sha256sum --check "$archive.sha256"
python3 -m zipfile -e "$archive" .
cd contextdb-codex-0.6.0-alpha.3-linux-x86_64
bash install.sh

install.sh verifies its bundled core, platform lock, and supply-chain receipts, installs the Codex marketplace and plugin, and completes a real 16-tool MCP handshake. Python 3.10+ and the Codex CLI are required, and an x64 build of Node.js 18+ must be available on PATH for the cross-platform MCP launcher. Python's portable ZIP extractor does not restore Unix executable bits; after all bundled receipts match, setup copies the non-executable package ELF through a no-follow descriptor into a separate owner-only 0700 runtime inode. The package payload is never chmodded or executed, so even a writer retaining its original file descriptor cannot change the activated runtime. The prerelease workflow repeats this exact standard-extraction path in an isolated Codex home.

Windows x86-64:

$archive = (Resolve-Path .\contextdb-codex-0.6.0-alpha.3-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.6.0-alpha.3-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. An x64 build of Node.js 18+ and the Codex CLI must be available on PATH.

From source

Clone only this repository for the normal prebuilt path. On Linux:

git clone https://github.com/mikhailbovt/ContextDB-Codex.git
cd ContextDB-Codex
bash install.sh

On Windows:

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

Either installer downloads and verifies its own pinned platform release. A sibling ContextDB checkout is needed only when developing or rebuilding the core yourself. The Windows developer override is:

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

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

Verify the installed inventory if needed:

codex plugin list --json

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

Verify the implementation

On Linux, run the isolated native lifecycle and release checks:

python3 scripts/test-linux-lifecycle.py --help
python3 scripts/test-linux-release-install.py --help
python3 scripts/contextdb-linux-release.py --help
python3 docs/release/validate-publication-kit.py

On Windows, with both repositories available:

.\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

Both platform lifecycle suites use 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 Linux suite also proves concurrent broker clients and recovery from an owner-only crash-stale Unix socket before maintenance. The Windows release additionally remains accepted in Windows PowerShell 5.1 and PowerShell 7. See the support matrix for the exact evidence boundary.

Backup, restore, reset, and uninstall

On Linux, use the guarded local lifecycle manager:

python3 scripts/manage-linux.py backup --destination "$HOME/contextdb-memory.cdb-backup"
python3 scripts/manage-linux.py restore --backup "$HOME/contextdb-memory.cdb-backup"
python3 scripts/manage-linux.py reset --confirm RESET-CONTEXTDB-MEMORY
python3 scripts/manage-linux.py uninstall

Data and immutable runtimes are removed only with separate opt-ins and an exact confirmation:

python3 scripts/manage-linux.py uninstall \
  --remove-marketplace \
  --purge-data \
  --purge-runtime \
  --confirm DELETE-CONTEXTDB-MEMORY

On Windows, back up to a new path outside live custody:

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

Restore a verified composite backup:

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

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

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

Remove only the installed plugin:

.\scripts\uninstall.ps1

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

.\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, Linux secret-file encryption, macOS/ARM64 compatibility, cloud sync, or a hosted MCP endpoint.

Documentation and policies

• Documentation map
• Support matrix
• Local MCP tool contract
• Local acceptance cases
• Contributing guide
• Code of Conduct
• Security policy
• Privacy notice
• Support policy
• Terms
• Changelog
• Apache-2.0 license

Support the project

If this plugin saves you from re-explaining the same architecture decision to an amnesiac robot, you can support development through GitHub Sponsors or Ko-fi. Sponsorship is appreciated, never required for use or support.