# AgentMemory for Codex on Windows

> **Published preview.19/r269.** The [fixed Release](https://github.com/M-T-D-N/agentmemory-codex-windows/releases/tag/v0.1.0-preview.19) contains four assets whose public downloads were verified by size and SHA-256. Payload build source: `7e66cd75702222aece989ac1c6be4c73aa004e7d`; tag source: `0d9ec592c127eb4c93479452d191b67b0baf3576` with [successful Windows CI](https://github.com/M-T-D-N/agentmemory-codex-windows/actions/runs/41381747290). This subsequent documentation-only main update and its own CI are separate; see the Release for the separate follow-up commit and CI status. The frozen tag and payload are not rebuilt.

> **Historical preview.18/r225:** The [fixed Release](https://github.com/M-T-D-N/agentmemory-codex-windows/releases/tag/v0.1.0-preview.18) provides the four verified assets, hashes and installation instructions. Tagged public source: `6359546a`; payload workspace source: `3632849b`. This post-publication main documentation and its CI are separate from the unchanged binary build source. Historical preview.17/r216 remains preserved.

<p align="center">
  <img src="assets/readme-banner.svg" alt="AgentMemory — independent memory for Codex on Windows, with managed capture, project-scoped recall and provenance" width="1120" />
</p>

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

[English](README.md) | [한국어](READMEs/README.ko-KR.md) | [日本語](READMEs/README.ja-JP.md)

<p align="center">
  <a href="https://github.com/M-T-D-N/agentmemory-codex-windows/actions/workflows/ci.yml"><img src="https://github.com/M-T-D-N/agentmemory-codex-windows/actions/workflows/ci.yml/badge.svg" alt="Windows CI" /></a>
  <img src="https://img.shields.io/badge/status-Technical_Preview-286b85" alt="Technical Preview" />
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0" /></a>
</p>

[Install without building](#install-without-building) · [Operating guide](packaging/windows-codex/README.md) · [Validation and limits](#validation-scope-and-known-limitations) · [Release notes](CHANGELOG.md)

> [!IMPORTANT]
> This is an independent Technical Preview. It is based on
> [AgentMemory](https://github.com/rohitg00/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](#ai-development-disclosure).

## Published preview.19 / r269

The fixed Release supplies the matched ZIP, TGZ launcher, descriptor and checksums.
Compatibility remains AgentMemory 0.9.30 / engine and SDK 0.22.1 / data contract 5.
See [changes, installation, update, recovery and bounded qualification](docs/PREVIEW_19.md).
Historical preview.18 and earlier tags/assets remain unchanged.

## Start here

The preview.19 release line 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.

Preview.19 is the published r269 Windows technical preview. The [fixed Release](https://github.com/M-T-D-N/agentmemory-codex-windows/releases/tag/v0.1.0-preview.19) records exact source identities, successful CI, download hashes and limits. Use only its matching launcher and ZIP; previous releases retain their own guides.

1. Check Windows x64, Node.js 24+, Windows PowerShell 5.1 and Codex desktop, then follow the [pinned installer guide](packaging/windows-codex/npm/README.md). 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](SUPPORT.md). 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](CHANGELOG.md). Source tags
identify public releases; each build manifest records its own qualification.

## Historical changes in preview.18

- Resume native capture across structurally validated `additional_tools` declarations; preserve conservative stops for unknown or malformed content.
- Serialize Qwen lease lifecycle across processes, verify process-start identity and honor foreground ownership.
- Remove development-only pnpm metadata from installed runtime inputs.
- Carry the earlier bounded decompression/correspondence and evidence-bound distribution fixes. See [qualification, installation/update/removal/recovery and limits](docs/PREVIEW_18.md). The r223 baseline and new package qualification are reported separately.

## 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](CHANGELOG.md) 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](packaging/windows-codex/README.md) for readiness
coordination, cursor recovery, and provider limits.

## Version identities

| Identity | Value | Meaning |
|---|---:|---|
| Downstream release | `0.1.0-preview.19` | Versioned 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`](upstream-source.json).

## Install without building

Use the matching preview.19 GitHub release ZIP or version-pinned TGZ launcher with the
[pinned npm/npx installation guide](packaging/windows-codex/npm/README.md).
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](https://docs.npmjs.com/cli/install/#allow-remote).

## 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.25.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`](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

Use the published version-tag checkout on Windows, then run the release builder from PowerShell.
The output directory must not already exist.

```powershell
git clone --branch v0.1.0-preview.19 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`](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](INSTALL_FOR_AGENTS.md).

## 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 operating memory database, actual user transcript or user export,
  API key, generated installer, or private development history.
- Security reports should use GitHub's private vulnerability reporting flow;
  see [`SECURITY.md`](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 configurations, other upstream language copies,
generated build output, and private monorepo history remain outside this public
snapshot. Four cloud entrypoint source files are retained only because the normal
Windows packaging suite directly tests their secret-output behavior; they do not add cloud support. 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

```powershell
pnpm install --frozen-lockfile
pnpm run skills:check
pnpm run typecheck
pnpm run build
pnpm test
```

For Windows adapter and packaging checks, use the
[agent runbook's source-check procedure](INSTALL_FOR_AGENTS.md#2-verify-the-source-checkout).
It reads the current adapter/packaging lists from `test-suites.json`, keeps
integration/curation disabled, and uses an explicit synthetic scratch directory.

The repository is marked `private` in package manifests to prevent accidental
publication under upstream `@agentmemory/*` package names. Contributions should
follow [`CONTRIBUTING.md`](CONTRIBUTING.md), and the downstream release history
is in [`CHANGELOG.md`](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`](NOTICE) and [`upstream-source.json`](upstream-source.json) for the
attribution and exact source identity. The code is provided under the
[Apache License 2.0](LICENSE).