AgentMemory for Codex on Windows

Independent, Windows-native AgentMemory downstream for OpenAI Codex Desktop and Codex CLI.

English | 한국어 | 日本語

Install without building · Operating guide · Validation and limits · Release notes

Important

This is an independent Technical Preview. It is based on AgentMemory v0.9.30, but it is not the official upstream repository, an @agentmemory/* npm release, or a promise of upstream support. Do not use an upstream npx command or the compatibility plugin manifests as a substitute for the Windows build and installer described here.

Development note: this downstream is AI-generated and user-tested; read the full disclosure.

Start here

Preview.16 packages AgentMemory 0.9.30 with the downstream-patched iii engine/SDK 0.22.1. The same installer supports an empty target, an owned managed installation, or an explicitly identified original upstream 0.9.29/0.9.30 file-backed installation. You do not need to install upstream first.

1. Check Windows x64, Node.js 24+, Windows PowerShell 5.1 and Codex desktop, then follow the pinned installer guide. The published release includes a prebuilt runtime; source builds are optional.
2. Preview the selected installation path, then use --execute. For an empty target the default path prepares, activates and validates the service; --fresh and --activate-prepared remain available for separate phases. Connect Codex MCP after service validation.
3. If a step fails, use support and recovery guidance. Report the release and failing phase with a short redacted error; do not attach memory databases or credentials.

What this preview does

AgentMemory preserves useful context across Codex tasks while keeping the official AgentMemory memory, lesson, graph, audit, and provenance stores as the only canonical stores.

• Captures normal main-agent user prompts and final assistant responses through four managed Codex hooks: SessionStart, UserPromptSubmit, Stop, and SessionEnd.
• Excludes ambient UI, title/fork traffic, known internal host prompts, and subagent traffic from durable capture.
• Keeps writes, deletion, curation, and provenance exact-project scoped.
• Supports audited, target-scoped live graph provenance correction with dry-run previews. Manual graph writes with multiple source groups must map every node and edge through zero-based sourceIndexes, or explicitly opt into shared provenance with sharedSources: true.
• Supports audited recovery of proven empty observations through the existing REST forget endpoint, with exact IDs, version checks and preserved graph cursors.
• Supports bounded, source-labelled federated recall across projects without allowing wildcard writes.
• Can use a credential-free, loopback-only local Qwen worker for typed graph extraction. Every other AgentMemory LLM feature receives the noop provider; external fallbacks remain disabled.
• Uses an authenticated loopback MCP endpoint for Codex and retains a packaged stdio launcher only as a compatibility path.

The upstream-compatible source surface contains 58 MCP tools. Its MCP surface is 58 tools, 6 resources, and 3 prompts; it also has 143 endpoints on port 3111, 12 portable hooks, and 17 skills. The supported Windows profile intentionally activates only the four managed hooks listed above.

For audits, MCP memory_recall, memory_smart_search, and memory_timeline accept trackAccess: false to avoid access-count reinforcement. The default remains true; visibility, project boundaries, and recovery guards still apply. Graph query shards are rebuildable indexes in the same iii StateModule as the canonical graph. Missing or dirty indexes use a bounded snapshot with a warning; only an explicit snapshot rebuild refreshes them.

Release changes are recorded in CHANGELOG.md. Source tags identify public releases; each build manifest records its own qualification.

Changes in preview.16

• Keeps memory replacement, slot updates, import and deletion within the exact project and agent owner, including partial acknowledgements and concurrent capture.
• Applies archive and pending-import visibility before recent-result limits; shows derived session summaries only while their canonical source digest still matches.
• Uses last activity to distinguish a long active session from an idle abandoned session.
• Records E2E write intent before dispatch and requires actual server completion before cleanup; request headers, body failures and parse failures have distinct outcomes.
• Adds successful installation backup closeout and bounded synthetic qualification without starting general LLM features.

Final package qualification is recorded in the release notes. Earlier installation evidence remains labelled with its original revision.

Changes in preview.15

• Integrates upstream AgentMemory 0.9.30 while preserving canonical source text, exact-project filtering and graph provenance.
• Uses one installer for new installations, managed updates and qualified original upstream adoption; newer unsupported upstream versions are retained rather than silently downgraded.
• Pins iii 0.22.1 with the file flush barrier and bounded state/stream pagination. Acknowledged managed writes wait for the barrier; process-crash qualification does not certify power-loss recovery.
• Settles deliberately skipped captures without false dead letters and distinguishes graph-provider availability from intentionally disabled general LLM features.
• Removes each successful build invocation's own disposable scratch unit; failures remain available for diagnosis. Shared caches, release packages and canonical data are separate.

See release notes for verification scope and retained limitations.

How search, filtering, and indexes work

Normal recall searches stored observations and reusable lessons. Keyword retrieval uses BM25 with Korean inflection and literal identifier handling. Where available, vector and stored-graph candidates join the same ranked result set. A graph search reads existing nodes, edges, and source references; it does not ask local Qwen to answer the query. Qwen is used separately for background graph extraction in the supported Windows profile.

Search candidates are checked against their canonical observation and session. Project, speaker, archive, and ambient-source eligibility apply before selecting the returned result count. Literal code and quoted source text are preserved; ambient-looking text inside those regions is not automatically discarded. Use memory_smart_search for compact candidates, then expandIds to inspect the original observations and their provenance. Use an exact registered project ID; * is an intentional federated read, not permission for cross-project writes.

The keyword snapshot and graph-query shards are rebuildable derived indexes. Compacting the keyword representation does not delete conversations, change observation IDs, or remove their canonical source text. Preview.13 reduced the measured keyword snapshot text size by 63.6% with preserved posting order and scores. Graph output is also derived: verify consequential conclusions against source observations rather than treating an extracted relationship as a fact.

Preview.14 fixes multi-seed graph retrieval: when several matched entities or source chunks reach the same observation, the strongest candidate wins together with its context and provenance. A weak path discovered first can no longer hide a later direct match. Expansion continues excluding the input observations, and existing project and source-visibility checks remain in place.

Validation scope and known limitations

The existing checks cover package behavior, managed hooks, capture/filtering, authenticated MCP/REST, graph provenance, installer/recovery, and packaged CLI/MCP entrypoints. Regression tests exercise connected graph seeds in both orders, stronger direct matches, shorter expansion paths, provenance replacement, and result limits. The fixed live historical set contains 50 questions with original observation IDs; it measures retrieval on the installed runtime rather than assuming that unit tests prove live success. Exact release results are published in the release notes.

A preview.13 investigation reproduced an intermittent roughly six-second caller response. Native MCP completion took about 1.4 seconds; roughly 4.5 seconds followed that completion before the calling script resumed. The precise post-completion cause and any influence from concurrent conversations remain unknown. Qwen inference is not part of that search path. The graph-ranking fix is a separate confirmed defect and is not presented as a fix for this intermittent delay.

AdGuard/redirect-driver interoperability remains unqualified. Validation on one Windows/Codex host is not certification of every host configuration or every upstream-compatible operation. The binaries remain unsigned; SHA-256 checks verify artifact integrity, not publisher signing. See the installation guide for preparation, activation, update, data preservation, and rollback boundaries.

When the graph updates

1. The managed hooks store eligible conversation turns as observations. A new committed observation wakes the existing graph backlog scheduler; rejected or duplicate observations do not. A wake failure leaves the observation intact.
2. The current Codex model selects reusable decisions and verified fixes through official memory, lesson, and graph curation tools with source provenance. Storing a final answer alone does not mark it as a verified decision.
3. If the optional local Qwen graph provider is configured and available, the scheduler enriches the graph in bounded batches. Runtime readiness must be stable for 15 seconds; an observation wake reuses an already stable runtime without restarting that wait. Drains run up to four batches, with a 30-second cooldown before continuing full drains. A 15-minute probe covers missed wakes and restarts. Foreground Qwen work can defer extraction without advancing the cursor.

The Windows adapter now requests conditional Qwen startup automatically when the configured provider is unavailable and the existing backlog selector finds processable observations. It uses the workspace's existing LocalAI launcher; manual holds, GPU/RAM admission and shared-consumer protection stay with that launcher. Failed admission is retried on the 15-minute recovery cycle. Only an instance started by this worker is released after five minutes of empty backlog. No LocalAI installation or universal memory threshold is bundled. Hosts without that integration continue using an already running provider. Provider-free manual curation and deterministic structural extraction remain available.

See the operating guide for readiness coordination, cursor recovery, and provider limits.

Version identities

Identity	Value	Meaning
Downstream release	0.1.0-preview.16	Public source tag and pinned installer distribution
AgentMemory compatibility	0.9.30	CLI, MCP, package, API, export, and installed-runtime compatibility
Qualification revision	Build manifest	Internal build provenance, not a public version line
iii engine	0.22.1	Pinned patched native runtime input, verified by SHA-256 during the build

The exact upstream tag, commit, tree, and pristine package hash are recorded in upstream-source.json.

Install without building

Use the preview.16 GitHub release ZIP or its version-pinned TGZ launcher with the pinned npm/npx installation guide. It covers automatic empty-root installation, optional separate preparation/activation, managed updates, original upstream adoption, and offline hash verification. The GitHub TGZ can be run with npm without a separate npm-registry publication. Users need Windows x64, Node.js 24+, and Codex; pnpm, Python, and compilers are only needed by source builders.

npm 12 blocks remote TGZ packages by default. The installer command includes --allow-remote=root for the explicitly selected launcher; it does not change global npm settings. See the npm policy.

Source-build requirements

• Windows with PowerShell 5.1 or newer; this preview is qualified on Windows 11
• Node.js 24 or newer
• Python 3 on PATH for the plaintext HTTP regression tests (CI uses Python 3.12)
• pnpm 11.19.0 through the repository's pinned package-manager declaration
• The pinned downstream-patched iii engine 0.22.1 Windows executable whose SHA-256 matches packaging/windows-codex/config/third-party-inputs.json

The npm launcher uses a prebuilt release ZIP. The binaries are not Authenticode-signed; the pinned npm descriptor, ZIP SHA-256 and per-file manifest provide integrity checks.

Build and evaluate from source

Clone the repository on Windows, then run the release builder from PowerShell. The output directory must not already exist.

git clone --branch v0.1.0-preview.16 https://github.com/M-T-D-N/agentmemory-codex-windows.git
Set-Location agentmemory-codex-windows

& .\packaging\windows-codex\Build-WindowsCodex.ps1 `
  -OutputDirectory D:\staging\agentmemory-codex `
  -IiiEnginePath D:\inputs\iii-0.22.1.exe `
  -ScratchDirectory D:\staging\agentmemory-build-temp `
  -ReleaseRevision r199

The normal builder verifies the pinned native input, restores the frozen lock, checks generated skills, type-checks, builds, runs the package and Codex adapter tests, creates a production dependency tree, and writes a complete immutable file manifest.

The installer is dry-run by default. It validates release hashes, ownership, paths, and the existing installation before changing anything. Review the exact build, dry-run, cutover, rollback, retention, and authentication contract in packaging/windows-codex/README.md before using -Execute.

Warning

The Windows installer is designed for an owned, managed AgentMemoryCodex service layout. Do not point it at an unrelated directory or treat build output as user data. Canonical data, secrets, logs, task identity, and rollback state have independent lifecycles.

Updating an existing installation

Check out the release tag into a source checkout and use a fresh staging directory. Choose a new -ReleaseRevision rN that is not already installed; r83 in the examples is a build label, not permission to overwrite an existing r83 runtime. Run the installer dry-run against the same owned installation, review the exact predecessor and target, and follow the approved cutover and rollback procedure. Canonical data, secrets, and instance metadata stay in the installation. Do not copy data into the source tree or invoke the historical one-off session-stub migrations removed from this preview. See the agent runbook.

Privacy and security boundaries

• MCP and service traffic stay on authenticated loopback endpoints in the supported profile.
• The optional Qwen provider accepts only credential-free loopback HTTP and is capability-scoped to graph extraction.
• The source tree contains no memory database, session transcript, user export, API key, generated installer, or private development history.
• Security reports should use GitHub's private vulnerability reporting flow; see SECURITY.md.

Repository map

Path	Purpose
src/	AgentMemory compatibility source
packaging/windows-codex/	Supported Windows/Codex adapter, builder, installer, and tests
plugin/	Upstream-compatible plugin assets bundled into the source build; not the supported installation path
test/	Unit and security regression tests
benchmark/, eval/	Upstream-derived harnesses and historical reference results; not Windows preview qualification
integrations/	Compatibility integrations; not separately supported downstream products
upstream-source.json	Exact upstream provenance

The upstream marketing website, cloud deployment examples, other upstream language copies, generated build output, and private monorepo history are intentionally outside the first public repository snapshot. Historical benchmark material is retained only for reproducibility and is explicitly labelled as upstream reference; no benchmark number in those directories is a claim for this downstream preview.

Development checks

pnpm install --frozen-lockfile
pnpm run skills:check
pnpm run typecheck
pnpm run build
pnpm test
node packaging/windows-codex/tests/codex-turn.test.mjs

The repository is marked private in package manifests to prevent accidental publication under upstream @agentmemory/* package names. Contributions should follow CONTRIBUTING.md, and the downstream release history is in CHANGELOG.md.

AI development disclosure

Most downstream modifications were generated and revised by OpenAI Codex from user-provided requirements and iterative acceptance requests. The repository owner did not manually review the source code. Validation is based on automated tests and live functional testing in the owner's Windows/Codex environment. No independent third-party code or security audit has been performed.

In short: AI-generated, user-tested, not manually code-reviewed.

Upstream attribution and license

This downstream is based on AgentMemory by Rohit Ghumare and contributors. See NOTICE and upstream-source.json for the attribution and exact source identity. The code is provided under the Apache License 2.0.