# ContextDB Memory [Health: Active] **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/mikhailbovt/ContextDB-Codex **GitHub Stars:** 1 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/contextdb-memory ## Description Local-first durable AI memory with policy-bound recall and a typed project graph. ## Claude Desktop Quick Installation Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client: ```json "mcpServers": { "contextdb-memory": { "url": "https://img.shields.io/badge/license-Apache--2.0-718cff.svg)](LICENSE" } } ``` ## Documentation & README
ContextDB Memory for Codex — Give every task a past
[![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-718cff.svg)](LICENSE) [![Windows + Linux x86-64](https://img.shields.io/badge/platform-Windows%20%2B%20Linux%20x86--64-36bdd2.svg)](docs/release/support-matrix.md) [![0.6.0 alpha](https://img.shields.io/badge/release-0.6.0--alpha.3-bb73ff.svg)](https://github.com/mikhailbovt/ContextDB-Codex/releases/tag/v0.6.0-alpha.3) **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)
--- 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 ```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 local 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. 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. ```powershell 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](https://github.com/mikhailbovt/ContextDB-Codex/releases), verify the matching `.sha256` sidecar, and install it locally. **Linux x86-64:** ```bash 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:** ```powershell $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: ```bash git clone https://github.com/mikhailbovt/ContextDB-Codex.git cd ContextDB-Codex bash install.sh ``` On Windows: ```powershell 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: ```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 On Linux, run the isolated native lifecycle and release checks: ```bash 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: ```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 ``` 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](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/docs/release/support-matrix.md) for the exact evidence boundary. ## Backup, restore, reset, and uninstall On Linux, use the guarded local lifecycle manager: ```bash 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: ```bash 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: ```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, Linux secret-file encryption, macOS/ARM64 compatibility, cloud sync, or a hosted MCP endpoint. ## Documentation and policies - [Documentation map](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/docs/README.md) - [Support matrix](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/docs/release/support-matrix.md) - [Local MCP tool contract](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/docs/reference/tool-contract.md) - [Local acceptance cases](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/docs/testing/local-acceptance-cases.md) - [Contributing guide](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/CONTRIBUTING.md) - [Code of Conduct](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/CODE_OF_CONDUCT.md) - [Security policy](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/SECURITY.md) - [Privacy notice](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/PRIVACY.md) - [Support policy](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/SUPPORT.md) - [Terms](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/TERMS.md) - [Changelog](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/CHANGELOG.md) - [Apache-2.0 license](https://github.com/mikhailbovt/ContextDB-Codex/blob/HEAD/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](https://github.com/sponsors/mikhailbovt) or [Ko-fi](https://ko-fi.com/mikhailbovt). Sponsorship is appreciated, never required for use or support.