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