{ "markdown": "
\n \"ContextDB\n\n
\n\n [![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-718cff.svg)](LICENSE)\n [![Windows + Linux x86-64](https://img.shields.io/badge/platform-Windows%20%2B%20Linux%20x86--64-36bdd2.svg)](docs/release/support-matrix.md)\n [![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)\n\n **Automatic project continuity for Codex, backed by a local ContextDB memory graph.**\n\n [Install](#install) · [See it grow](#how-the-memory-grows) · [Operate safely](#backup-restore-reset-and-uninstall)\n
\n\n---\n\nCodex can understand a repository brilliantly and still wake up in the next task with the\nemotional continuity of a goldfish. ContextDB Memory gives it a durable, local project history:\nthe decisions already made, constraints that still matter, goals in flight, verified milestones,\nand open loops waiting for somebody to stop pretending they do not exist.\n\nThe plugin recalls relevant context at the start of substantive work and checkpoints significant\nstate as the task evolves. It does this through a bundled, listener-free MCP adapter; the database,\nruntime, keys, and mutable memory remain on your own Windows or Linux computer.\n\n> **Release status:** `0.6.0-alpha.3` Developer Preview for **Windows x86-64 and Linux x86-64**.\n> Both local profiles include automatic hooks, a typed candidate graph, platform-specific custody,\n> recovery and uninstall controls, and independently verifiable release bundles. Executables are\n> unsigned, macOS and ARM64 are not supported, and this is not a hosted ContextDB service.\n> The Linux ELF uses an Ubuntu 22.04 / glibc 2.35 baseline; other glibc-based\n> x86-64 distributions require glibc 2.35 or newer and are not individually certified.\n\n## What it remembers\n\n| Memory kind | Example | Why it survives |\n| --- | --- | --- |\n| Decision | “Keep the local edition stdio-only.” | Prevents a later task from reopening a settled architecture choice without evidence |\n| Constraint | “Do not publish or start containers during this phase.” | Keeps execution inside the project's real boundary |\n| Goal | “Prepare both repositories for the first public alpha.” | Lets future work resume against the intended outcome |\n| Open loop | “Code signing still needs publisher custody.” | Preserves unfinished work without pretending it is complete |\n| Milestone | “Lifecycle suite passed in PowerShell 5.1 and 7.” | Carries forward a verified result with provenance |\n| Preference | “Keep internal RFCs local, not public.” | Maintains durable project conventions |\n| Fact or evidence summary | “The packaged core has network listeners disabled.” | Gives recall a compact, traceable technical anchor |\n\nShort-lived chatter, guesses, copied logs, secrets, and “maybe someday” noise should not become\ndurable memory. The active Codex model decides whether a change is significant; the host contract\nconstrains how it may be written.\n\n## How the memory grows\n\n```mermaid\nflowchart LR\n S[Session starts] --> R[Bounded candidate recall]\n R --> W[Codex works with current files]\n W --> C{Durable change?}\n C -- no --> W\n C -- yes --> Q[Quarantined candidate]\n Q --> G[Project / topic / memory DAG]\n G --> R\n Q -. explicit successor .-> Q2[New revision]\n```\n\n- `SessionStart` loads the safety and continuity contract for new, resumed, cleared, and compacted\n sessions.\n- `UserPromptSubmit` creates at most one bounded recall opportunity when a prompt starts or\n materially changes a substantive workspace task.\n- During work and at the loop-safe `Stop` checkpoint, Codex can capture significant decisions,\n constraints, preferences, goals, open loops, and verified milestones automatically—no special\n “remember this” incantation required.\n- Stable project, topic, and memory identities make retries converge. A changed fact becomes an\n explicit successor instead of silently overwriting its predecessor.\n- Multi-parent links let a memory belong to its project or topic while also connecting to a related\n decision, goal, or open loop.\n\nThe hooks create the opportunity and the instructions for automatic memory; they do not turn every\ntoken into immortal sludge. Review the bundled hooks when Codex asks you to trust them, and start a\nnew task after install or update so the host loads the current package.\n\n## Built to distrust its own memory\n\nAutomatic records are typed **candidates**, not canonical truth.\n\n```text\nmodel output → deterministic identity + policy checks → quarantined candidate\n ↛ canonical memory\n```\n\nThe model-facing MCP surface cannot promote, correct, overwrite, or delete canonical semantic\nmemory. Before using a candidate, the skill materializes it, traverses its hierarchy, and verifies\nthat the route reaches the active checkout's project root. Recalled content remains untrusted data:\nit is never interpolated into a shell command or treated as authority.\n\nThat caution is intentional. Durable hallucinations are just bugs with tenure.\n\n## Architecture\n\n```mermaid\nflowchart LR\n subgraph Host[Codex host]\n H[Lifecycle hooks] --> K[ContextDB memory skill]\n K --> M[MCP tools]\n end\n M -->|stdio| P[Local MCP proxy]\n P --> B[Single-owner local broker]\n B --> D[(ContextDB native store)]\n D -->|authorized, bounded recall| M\n```\n\nThe packaged core must report:\n\n```text\nbuild_profile local-mcp\nnetwork_listeners disabled\n```\n\nThe launcher rejects a binary outside that profile. Windows uses an authenticated named-pipe\nbroker and CurrentUser DPAPI custody; Linux uses an authenticated owner-only Unix-domain socket,\n`0700` directories, `0600` key and state-head files, and the XDG data hierarchy. Linux file\npermissions are not transparent encryption: use your operating system's disk encryption when that\nstronger at-rest boundary matters. Mutable custody lives outside both the source checkout and\nCodex's versioned plugin cache. Neither profile requires a publisher-operated backend, analytics\nservice, cloud synchronization, or OpenAI API key.\n\n## Install\n\n### From the Codex marketplace\n\nThis is the smallest install path. It needs **one public repository**, not a ContextDB source\ncheckout. Before adding it, verify that `node --version` reports v18 or newer; Linux also needs\n`python3 --version` to report 3.10 or newer. The repository installers perform these checks\nautomatically, while a raw marketplace add cannot run code before Codex caches the plugin.\n\n```powershell\ncodex plugin marketplace add mikhailbovt/ContextDB-Codex --ref v0.6.0-alpha.3\ncodex plugin add contextdb-memory@contextdb-codex\n```\n\nStart a new Codex task after installation. On the first MCP start, the plugin detects its host OS,\ndownloads the exact ContextDB core ZIP pinned by the matching platform lock, and checks its canonical\nGitHub Release URL, byte length, archive SHA-256, safe ZIP layout, executable SHA-256,\nlistener-free build profile, target-specific SBOM, dependency notices, and Rust licenses. It then\ninitializes Windows CurrentUser DPAPI custody or Linux owner-only local custody. Mutable memory is\nstored outside the versioned plugin cache. Both platforms require an x64 build of Node.js 18+ on `PATH` for the\nmarketplace MCP dispatcher; Linux additionally requires Python 3.10+ but not PowerShell. Neither\nplatform requires a ContextDB checkout, Docker, or a remote MCP service.\n\n### From the self-contained release\n\nEach platform has one complete release ZIP; there is no second repository or runtime download.\nChoose your operating system from\n[Releases](https://github.com/mikhailbovt/ContextDB-Codex/releases), verify the matching `.sha256`\nsidecar, and install it locally.\n\n**Linux x86-64:**\n\n```bash\narchive=contextdb-codex-0.6.0-alpha.3-linux-x86_64.zip\nsha256sum --check \"$archive.sha256\"\npython3 -m zipfile -e \"$archive\" .\ncd contextdb-codex-0.6.0-alpha.3-linux-x86_64\nbash install.sh\n```\n\n`install.sh` verifies its bundled core, platform lock, and supply-chain receipts, installs the\nCodex marketplace and plugin, and completes a real 16-tool MCP handshake. Python 3.10+ and the\nCodex CLI are required, and an x64 build of Node.js 18+ must be available on `PATH` for the cross-platform MCP\nlauncher. Python's portable ZIP extractor does not restore Unix executable bits; after all bundled\nreceipts match, setup copies the non-executable package ELF through a no-follow descriptor into a\nseparate owner-only `0700` runtime inode. The package payload is never chmodded or executed, so even\na writer retaining its original file descriptor cannot change the activated runtime. The prerelease\nworkflow repeats this exact standard-extraction path in an isolated Codex home.\n\n**Windows x86-64:**\n\n```powershell\n$archive = (Resolve-Path .\\contextdb-codex-0.6.0-alpha.3-windows-x86_64.zip).Path\n$expected = ((Get-Content \"$archive.sha256\" -Raw).Trim() -split '\\s+')[0].ToLowerInvariant()\n$actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash.ToLowerInvariant()\nif ($actual -ne $expected) { throw \"Release checksum mismatch: $actual\" }\nExpand-Archive -LiteralPath $archive -DestinationPath .\nSet-Location .\\contextdb-codex-0.6.0-alpha.3-windows-x86_64\n.\\install.cmd\n```\n\nThe release already contains the verified ContextDB executable, dependency notices, CycloneDX\nSBOM, Rust runtime licenses, lifecycle scripts, plugin, and public documentation. The installer\nruns without downloading a second repository or runtime. An x64 build of Node.js 18+ and the Codex CLI must be\navailable on `PATH`.\n\n### From source\n\nClone only this repository for the normal prebuilt path. On Linux:\n\n```bash\ngit clone https://github.com/mikhailbovt/ContextDB-Codex.git\ncd ContextDB-Codex\nbash install.sh\n```\n\nOn Windows:\n\n```powershell\ngit clone https://github.com/mikhailbovt/ContextDB-Codex.git\nSet-Location ContextDB-Codex\n.\\scripts\\install.ps1\n```\n\nEither installer downloads and verifies its own pinned platform release. A sibling ContextDB\ncheckout is needed only when developing or rebuilding the core yourself. The Windows developer\noverride is:\n\n```powershell\n.\\scripts\\install.ps1 -ContextDbRepo ..\\ContextDB\n```\n\nRust `1.97.1` is required only for that optional source-build path.\n\nVerify the installed inventory if needed:\n\n```powershell\ncodex plugin list --json\n```\n\nStart a new Codex task after any installation path so Codex loads the current hooks and skill.\n\n## Verify the implementation\n\nOn Linux, run the isolated native lifecycle and release checks:\n\n```bash\npython3 scripts/test-linux-lifecycle.py --help\npython3 scripts/test-linux-release-install.py --help\npython3 scripts/contextdb-linux-release.py --help\npython3 docs/release/validate-publication-kit.py\n```\n\nOn Windows, with both repositories available:\n\n```powershell\n.\\scripts\\test-hooks.ps1\n.\\scripts\\test-mcp.ps1\n.\\scripts\\test-auto-hierarchy.ps1\n.\\scripts\\test-custody.ps1 -ContextDbRepo ..\\ContextDB\n.\\scripts\\test-lifecycle.ps1 -ContextDbRepo ..\\ContextDB\npython .\\docs\\release\\validate-publication-kit.py\n```\n\nBoth platform lifecycle suites use isolated temporary custody and an isolated Codex home to\nexercise setup, MCP startup, backup, restore, recoverable reset, marketplace installation,\ncustom-root purge, runtime purge, and uninstall. The Linux suite also proves concurrent broker\nclients and recovery from an owner-only crash-stale Unix socket before maintenance. The Windows\nrelease additionally remains accepted in Windows PowerShell 5.1 and PowerShell 7. See the\n[support matrix](docs/release/support-matrix.md) for the exact evidence boundary.\n\n## Backup, restore, reset, and uninstall\n\nOn Linux, use the guarded local lifecycle manager:\n\n```bash\npython3 scripts/manage-linux.py backup --destination \"$HOME/contextdb-memory.cdb-backup\"\npython3 scripts/manage-linux.py restore --backup \"$HOME/contextdb-memory.cdb-backup\"\npython3 scripts/manage-linux.py reset --confirm RESET-CONTEXTDB-MEMORY\npython3 scripts/manage-linux.py uninstall\n```\n\nData and immutable runtimes are removed only with separate opt-ins and an exact confirmation:\n\n```bash\npython3 scripts/manage-linux.py uninstall \\\n --remove-marketplace \\\n --purge-data \\\n --purge-runtime \\\n --confirm DELETE-CONTEXTDB-MEMORY\n```\n\nOn Windows, back up to a new path outside live custody:\n\n```powershell\n.\\scripts\\backup.ps1 -Destination D:\\Backups\\contextdb-memory.cdb-backup\n```\n\nRestore a verified composite backup:\n\n```powershell\n.\\scripts\\restore.ps1 -Backup D:\\Backups\\contextdb-memory.cdb-backup\n```\n\nCreate fresh custody while preserving the old state in a timestamped recovery directory:\n\n```powershell\n.\\scripts\\reset.ps1 -ConfirmReset RESET-CONTEXTDB-MEMORY\n```\n\nRemove only the installed plugin:\n\n```powershell\n.\\scripts\\uninstall.ps1\n```\n\nData and immutable runtimes require separate opt-in flags and an exact confirmation token:\n\n```powershell\n.\\scripts\\uninstall.ps1 `\n -RemoveMarketplace `\n -PurgeData `\n -PurgeRuntime `\n -ConfirmPurge DELETE-CONTEXTDB-MEMORY\n```\n\nFilesystem removal is not a promise of forensic secure erasure. Backups and host conversation\nhistory remain separate copies.\n\n## Deliberate nonclaims\n\nThis preview does not claim deterministic canonical adjudication, forensic hard deletion,\nKMS/HSM custody, provider-copy erasure, semantic-scale certification, Authenticode signing,\nLinux secret-file encryption, macOS/ARM64 compatibility, cloud sync, or a hosted MCP endpoint.\n\n## Documentation and policies\n\n- [Documentation map](docs/README.md)\n- [Support matrix](docs/release/support-matrix.md)\n- [Local MCP tool contract](docs/reference/tool-contract.md)\n- [Local acceptance cases](docs/testing/local-acceptance-cases.md)\n- [Contributing guide](CONTRIBUTING.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security policy](SECURITY.md)\n- [Privacy notice](PRIVACY.md)\n- [Support policy](SUPPORT.md)\n- [Terms](TERMS.md)\n- [Changelog](CHANGELOG.md)\n- [Apache-2.0 license](LICENSE)\n\n## Support the project\n\nIf this plugin saves you from re-explaining the same architecture decision to an amnesiac robot,\nyou can support development through [GitHub Sponsors](https://github.com/sponsors/mikhailbovt) or\n[Ko-fi](https://ko-fi.com/mikhailbovt). Sponsorship is appreciated, never required for use or\nsupport.\n", "bytes": 14413, "sha": "412f73e261b2c79665bdded57aee6038a7179e860eed0ceb03b17f6b1b0322bb", "repo_slug": "mikhailbovt/contextdb-codex", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_mikhailbovt_contextdb_memory_72931750/readme" }