Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: document Claude Code Windows hook runner
AkitaOnRailsff8a926c79ba
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5eece20c..1c8d1518 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).## [Unreleased]+### Fixed+- Claude Code hook installs on native Windows now render Git Bash-compatible+ `bash -c` commands that keep the POSIX `.sh` hook scripts and convert+ drive-letter paths to Git Bash paths, matching Claude Code's actual hook+ runner instead of emitting PowerShell commands ([#45]).## [0.5.1] - 2026-05-27### Changeddiff --git a/README.md b/README.mdindex e017e3b6..3af2f73c 100644--- a/README.md+++ b/README.md@@ -21,7 +21,7 @@| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. || macOS | Supported | Workspace tests run in CI; native source builds are supported. Docker images run natively on Apple Silicon via the `linux/arm64` manifest. || Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |-| Native Windows | Experimental | PowerShell wrapper and `.ps1` hooks are available; real agent harness feedback still needed. See [`docs/windows.md`](docs/windows.md). |+| Native Windows | Experimental | PowerShell wrapper is available. Claude Code uses Git Bash `.sh` hooks on native Windows; other script-hook agents use the current PowerShell defaults pending harness feedback. See [`docs/windows.md`](docs/windows.md). || Claude Code | Supported | MCP config + lifecycle hooks. || Codex | Supported | MCP config + lifecycle hooks. || OpenCode | Supported | Remote MCP config + generated TypeScript plugin. |@@ -236,9 +236,10 @@ use `--mcp-url` if you installed MCP with a custom endpoint, and### Install Notes-- **Windows:** use the Linux path inside WSL2, or the native PowerShell- wrapper and `.ps1` hooks for native Windows agents. Do not mix path- worlds. See [`docs/windows.md`](docs/windows.md).+- **Windows:** use the Linux path inside WSL2, or the native Windows wrapper+ from PowerShell/cmd. Native Claude Code uses Git Bash `.sh` hooks; other+ script-hook agents use PowerShell defaults. Do not mix path worlds. See+ [`docs/windows.md`](docs/windows.md).- **Docker compose:** `docker compose -f docker/docker-compose.yml up -d`is supported; agent setup is the same as step 3 above.- **Remote server:** set `AI_MEMORY_SERVER_URL=http://<server-ip>:49374`diff --git a/docs/install.md b/docs/install.mdindex fda3f6c0..42b151ec 100644--- a/docs/install.md+++ b/docs/install.md@@ -410,6 +410,9 @@ Cursor, Gemini CLI, Antigravity CLI, and OpenClaw have lifecycle capture paths t> Gemini CLI, and Antigravity CLI use shell/PowerShell hook scripts: (1) `docker cp` the> bundled scripts to your home dir, (2) `docker run --rm install-hooks`> to render the config snippet.+> On native Windows, Claude Code is the exception to the PowerShell default:+> it runs hooks through Git Bash, so ai-memory renders `bash -c` commands for+> the `.sh` scripts.> OpenClaw, OpenCode, and OMP are different: they use generated> TypeScript plugin/extension files, so no shell-script extraction is> needed for those clients.@@ -609,8 +612,9 @@ server's environment.On Windows, see [`docs/windows.md`](windows.md). The short version: runthe install commands from the same environment that launches the agent.-WSL2-launched agents need WSL paths and POSIX `.sh` hooks; native Windows-agents need Windows paths and PowerShell `.ps1` hooks.+WSL2-launched agents need WSL paths and POSIX `.sh` hooks. Native Claude Code+uses Git Bash `.sh` hooks with Windows paths converted to `/c/...`; other+native Windows script-hook agents use PowerShell `.ps1` defaults.When run from source, `install-hooks` finds the bundled scripts inthe repo's `hooks/` automatically:diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 05d202b9..fb2db0b2 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -23,7 +23,9 @@ Claude Code, OpenAI Codex, Cursor, Gemini CLI, Antigravity CLI, OpenClaw, OpenCoOMP have automatic capture integrations (shell/PowerShell hooks forClaude Code / Codex / Cursor / Gemini CLI / Antigravity CLI, TypeScript plugin/extensionfiles for OpenClaw / OpenCode / OMP) and are covered in the-[main README](../README.md#quick-start).+[main README](../README.md#quick-start). On native Windows, Claude Code uses+Git Bash `.sh` hooks rather than the PowerShell default used by other+script-hook agents.Claude Desktop is **MCP-only** here: it exposes long-term memory to itsLLM via ai-memory's MCP tools (`memory_query`, `memory_recent`,diff --git a/docs/windows.md b/docs/windows.mdindex 1b124055..dee4b750 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -16,7 +16,11 @@ launches Claude Code, Codex, Cursor, Gemini CLI, or another agent.The difference matters because hook configs contain executable paths.WSL2 agents need Linux paths and POSIX `.sh` hooks. Native Windows-agents need Windows paths and PowerShell `.ps1` hooks.+agents need Windows paths, but the hook runner is agent-specific:+Claude Code invokes hooks through Git Bash, so ai-memory renders+`bash -c` commands that call `.sh` scripts with Git Bash paths+(`/c/Users/...`). Other native Windows script-hook agents keep the+PowerShell `.ps1` default until their harness behavior is verified.## Scenario A: Everything Inside WSL2@@ -93,12 +97,14 @@ ai-memory install-hooks --agent claude-code --apply```In this mode, the PowerShell wrapper runs the Linux container but tells-the CLI to render Windows hook commands:+the CLI to render hook commands for the native Windows agent:- Config files are written through the mounted Windows home directory.- Hook scripts are staged under `$HOME\.local\share\ai-memory\hooks\`.-- Hook commands explicitly call `powershell.exe`.-- Hook commands point at `.ps1` scripts.+- Claude Code hook commands call `bash -c` and point at `.sh` scripts using+ Git Bash paths such as `/c/Users/alice/...`.+- Other native Windows script-hook agents currently call `powershell.exe` and+ point at `.ps1` scripts.Use the matching `--client` / `--agent` values for other clients, forexample `codex`, `cursor`, or `gemini-cli`.@@ -130,17 +136,20 @@ target\debug\ai-memory.exe install-mcp --client claude-code --applytarget\debug\ai-memory.exe install-hooks --agent claude-code --apply```-Native Windows builds automatically render `.ps1` lifecycle hooks. The-hook bundle ships matching `.sh` and `.ps1` event scripts, and tests-enforce one-to-one event/agent parity between them.+Native Windows builds render agent-specific lifecycle hooks. Claude Code uses+Git Bash-compatible `.sh` commands on native Windows; other script-hook agents+use the PowerShell `.ps1` default. The hook bundle ships matching `.sh` and+`.ps1` event scripts, and tests enforce one-to-one event/agent parity between+them.## Current Harness CaveatsWindows hook support is new and needs real-world testing against nativeWindows agent builds.-- Claude Code may be used natively on Windows or from inside WSL2. Test- which process launches the hooks before assuming path format.+- Claude Code may be used natively on Windows or from inside WSL2. Native+ Claude Code invokes hooks through Git Bash; WSL2 Claude Code uses normal+ WSL paths.- Codex, OpenCode, Cursor, Gemini CLI, and OpenClaw may each choose differentWindows config locations or shell execution behavior. ai-memory usesthe current best-known defaults, but they need validation on real@@ -166,8 +175,9 @@ For native Windows:1. Run all install commands from PowerShell or `cmd.exe` using`ai-memory` / `ai-memory.ps1`.-2. Confirm generated hook commands reference `.ps1` files under your- Windows home directory.+2. Confirm generated hook commands match the agent: Claude Code should use+ `bash -c` plus `.sh` files with `/c/...` Git Bash paths; other script-hook+ agents should use `.ps1` files under your Windows home directory.3. Launch the native Windows agent.4. Call `memory_status` from the agent.5. Send a prompt, then run `ai-memory status` or `ai-memory recent`.