AgentMemory for Codex on Windows

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

English | 한국어 | 日本語

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

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 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. Graph completions use streamed SSE so long-running llama.cpp responses remain live and incomplete streams fail closed. Every other AgentMemory LLM feature receives the noop provider; external fallbacks remain disabled.

• Serves exact project, text, pagination, and bounded-walk graph reads from a rebuildable sharded index. A dirty or unavailable index falls back to an explicit bounded snapshot and never starts a full canonical graph scan.

• 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 56 MCP tools. Its MCP surface is 56 tools, 6 resources, and 3 prompts; it also has 133 endpoints on port 3111, 12 portable hooks, and 17 skills. The supported Windows profile intentionally activates only the four managed hooks listed above.

Non-reinforcing retrieval

memory_recall, memory_smart_search, and memory_timeline reinforce the access-based retention signal by default. Set trackAccess to false for administrative inspection, evaluation, reporting, previews, or other analytical reads that should not change that signal. This option does not bypass project scoping, agent isolation, result limits, or existing auditing.

Legacy empty session-end stubs

Internal qualification revision r62 adds a narrow maintenance migration for legacy rows that contain exactly a valid endedAt and status: "completed" but no recoverable session or observation data. It accepts explicit session IDs only, defaults to dry-run, refuses the entire batch if any row differs or has a session, observation, summary, memory, lesson, commit, crystal, or graph reference, and is audited and idempotent when applied. It is not a general session deletion API and does not authorize direct state-store edits.

Related MCP server: remem

Version identities

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

Requirements

• Windows with PowerShell 5.1 or newer; this preview is qualified on Windows 11

• Node.js 20 or newer

• pnpm 11.19.0 through the repository's pinned package-manager declaration

• The official iii engine 0.11.2 Windows executable whose SHA-256 matches packaging/windows-codex/config/third-party-inputs.json

No prebuilt or signed installer is attached to this source preview.

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 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.11.2.exe

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.

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

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.