Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(omp): clarify profile selection and install paths
Éverton Toffanettofed7d8014092
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ed5d849d..386624d7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -203,28 +203,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0now write `$CODEX_HOME/config.toml`, matching `hooks.json`; `uninstall`sweeps the legacy `~/.codex/config.toml` too, and `install-hooks` stillinfers the server URL and token from it until the entry is rewritten. (#820)-- OMP paths now follow OMP's own profile rules. A named profile (`--profile`,- `OMP_PROFILE`, or the legacy `PI_PROFILE`, previously ignored) owns- `~/.omp/profiles/<name>/agent` and ignores `PI_CODING_AGENT_DIR`, as OMP- does; `install-hooks` wrote the extension into `PI_CODING_AGENT_DIR`- instead, where that OMP never loads it. An empty, whitespace or `default`- profile selects the default profile rather than a `profiles/default` or- blank-named directory, a `PI_CODING_AGENT_DIR` a parent OMP derived for its- profile no longer leaks into the default profile, and a name OMP refuses is- refused. `install-mcp- --client omp` and auto-wire write `mcp.json` into the same agent dir instead- of always `~/.omp/agent`; `ai-memory run omp` imports sessions from it and- honors `PI_CODING_AGENT_SESSION_DIR` and a leading native `--profile`; `uninstall`- sweeps the active, default-profile and `~/.omp/agent` locations and no- longer aborts every agent's cleanup on an invalid profile name. ai-memory- also follows OMP's `PI_CONFIG_DIR`, which renames the `~/.omp` root (joined- under the home, as OMP joins it), for profiles, the extension, `mcp.json`,- session import and the `uninstall` sweep, which still covers the `~/.omp`- locations earlier releases wrote to; and on Linux and macOS `ai-memory run- omp`, `backfill` and `doctor` read sessions from `$XDG_DATA_HOME/omp/sessions`- (`$XDG_DATA_HOME/omp/profiles/<name>/sessions` for a named profile) when- that OMP directory exists and the agent dir is not relocated, as OMP does.- (#820)+- Corrected OMP's install and session paths for named profiles. Hooks and+ `mcp.json` now use the profile's agent directory and ignore+ `PI_CODING_AGENT_DIR`. Profile selection follows `--profile`, then+ `OMP_PROFILE`, then the legacy `PI_PROFILE`. Names are trimmed and+ validated; empty environment values, whitespace-only names and `default`+ select the default profile. Returning to the default profile also drops+ an agent directory inherited from a named parent profile.+ `PI_CONFIG_DIR` changes the `.omp` root relative to the user's home.+ On Linux and macOS, `run omp`, `backfill` and `doctor` read sessions from+ `$XDG_DATA_HOME/omp/sessions` (or `omp/profiles/<name>/sessions` under+ `$XDG_DATA_HOME`) when the corresponding OMP directory exists and the agent+ directory has not been relocated. `run omp` also honors+ `PI_CODING_AGENT_SESSION_DIR` and a leading native `--profile`.+ Uninstall checks the active and default profiles plus the legacy `.omp`+ locations, and an invalid OMP profile no longer stops cleanup for other+ agents. (#820)- A whitespace-only `KIMI_CODE_HOME`, `KIRO_HOME` or `GROK_HOME` pointedinstalls at a blank-named directory under the working directory, and awhitespace-only relocation variable did the same for `ai-memory run`'sdiff --git a/docs/install.md b/docs/install.mdindex 27abb166..ff7c052b 100644--- a/docs/install.md+++ b/docs/install.md@@ -1339,26 +1339,31 @@ not interchangeable — only Pi's bridges MCP tools.`omp --profile <name>` relocates OMP's agent home to`~/.omp/profiles/<name>/agent`. Point the installers at the same profile so-the extension and the MCP entry land where that profile loads them:+the extension and MCP entry are installed in that directory:```bashai-memory install-hooks --agent omp --profile work --apply-# or set it once for the shell, which install-mcp also reads:+# Or pass OMP_PROFILE to each installer:OMP_PROFILE=work ai-memory install-hooks --agent omp --applyOMP_PROFILE=work ai-memory install-mcp --client omp --apply```-The profile resolves the way OMP resolves it: `--profile` beats-`OMP_PROFILE`, which beats the legacy `PI_PROFILE` whenever it is set, even-to an empty value. Names are trimmed, an empty name or `default` selects the-default profile, and a name OMP refuses is refused here too. A named profile-ignores `PI_CODING_AGENT_DIR`, as OMP does; only the default profile honors-it. OMP's `PI_CONFIG_DIR` renames the `~/.omp` root (joined under your home,-as OMP joins it), and the extension and `mcp.json` follow it; an-`$XDG_DATA_HOME/omp` directory moves only OMP's sessions, never these files.-`uninstall --profile <name>` removes the same files, and also sweeps the-default profile's directory and the `~/.omp` locations earlier releases wrote-to, whatever `PI_CONFIG_DIR` says.+`--profile` takes precedence over `OMP_PROFILE`. The legacy `PI_PROFILE` is+used only when `OMP_PROFILE` is unset. Names are trimmed and validated using+OMP's rules. An empty environment value, a whitespace-only name or `default`+selects the default profile; an explicit `--profile ""` is rejected.++A named profile ignores `PI_CODING_AGENT_DIR`. The default profile uses it+unless it points to the named profile directory exported by a parent OMP+process. `PI_CONFIG_DIR` changes the `.omp` root relative to your home using+OMP's path-joining rules; it does not replace an explicit agent directory.+The extension and `mcp.json` stay in the agent directory even when sessions+move to XDG storage. See [native adapter behavior](managed-workstreams.md#native-adapter-behavior)+for the session paths.++`uninstall --profile <name>` removes the profile's integration files. It also+checks the default profile and the legacy `~/.omp` locations, including when+`PI_CONFIG_DIR` selects a different root.```bashai-memory install-hooks --agent pi --apply \diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 83090ab0..525d4905 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -381,10 +381,18 @@ is labelled completed evidence and must never be replayed as a pending call.| Command Code | native default creation | `--session <uuid>` | `~/.commandcode/projects/*/<uuid>.jsonl` || Kiro CLI v2 | native default creation | `--resume-id <uuid>` | `$KIRO_HOME/sessions/cli/<uuid>.jsonl` (+ sibling `<uuid>.json` metadata) || Kiro CLI v3 | native default creation with `--v3` | `--v3 --resume-id <sess_uuid>` | `$KIRO_HOME/sessions/<checkout-bucket>/<sess_uuid>/messages.jsonl` (+ sibling `session.json` metadata) |-| OMP | native default creation | `--resume=<id>` | `<agent dir>/sessions/**/*.jsonl`: `~/.omp/agent`, `~/.omp/profiles/<name>/agent` under a named profile, or `$PI_CODING_AGENT_DIR` for the default profile, with `~/.omp` renamed by `PI_CONFIG_DIR`; on Linux and macOS, `$XDG_DATA_HOME/omp/sessions` (`.../omp/profiles/<name>/sessions`) once that OMP directory exists and the agent dir is not relocated |+| OMP | native default creation | `--resume=<id>` | `<agent dir>/sessions/**/*.jsonl`, or the XDG session directory described below || Grok Build CLI | generated `--session-id` | `--resume <id>` | `$GROK_HOME/sessions/*/*/chat_history.jsonl` || Antigravity CLI | native default creation | `--conversation <id>` | `~/.gemini/antigravity-cli/conversations/<id>.db` metadata plus lifecycle-hook capture |+OMP's agent directory is `~/.omp/agent` for the default profile and+`~/.omp/profiles/<name>/agent` for a named profile. `PI_CONFIG_DIR` changes the+`.omp` root relative to the user's home. The default profile can also use+`PI_CODING_AGENT_DIR`. On Linux and macOS, sessions move to+`$XDG_DATA_HOME/omp/sessions`, or `$XDG_DATA_HOME/omp/profiles/<name>/sessions`+for a named profile, when that OMP directory exists and the agent directory+has not been relocated.+Command Code v3 transcripts are self-describing and append-only. The adapterrequires the UUID filename, header id, and canonical header `cwd` to agreebefore discovery or resume. Its 1.14.1 allowlist was checked against both the@@ -422,14 +430,17 @@ run a `crushrc` to read one set only there; pass `--data-dir` in that case. Natienvironment overrides are also honored:`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_DATA_HOME`,`PI_CODING_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR`, `KIMI_CODE_HOME`,-`KIRO_HOME`, and `GROK_HOME`, plus OMP's `PI_CONFIG_DIR` and profile (a-leading `--profile`, then `OMP_PROFILE`, then `PI_PROFILE`), which ignores-`PI_CODING_AGENT_DIR` as OMP does. A `--profile` later in the command line is-left to OMP; set-`OMP_PROFILE` (or `--env OMP_PROFILE=<name>`) when you need it there. A blank-value (empty or whitespace only) counts as unset everywhere: session import,-hooks and MCP all fall back to the default home, and `ai-memory run` removes-it from the launched harness's environment so the harness does too.+`KIRO_HOME`, and `GROK_HOME`, plus OMP's `PI_CONFIG_DIR`.+OMP profile selection follows a leading `--profile`, then `OMP_PROFILE`, then+`PI_PROFILE`. A named profile ignores `PI_CODING_AGENT_DIR`. A `--profile`+later in the command line is left to OMP; use `OMP_PROFILE` or+`--env OMP_PROFILE=<name>` so ai-memory can resolve the same profile.++Blank directory overrides (empty or whitespace-only values) count as unset.+Session import, hooks and MCP use their fallback paths, and `ai-memory run`+removes those values from the child environment. Profile variables follow a+different rule: an empty `OMP_PROFILE` selects the default profile and still+takes precedence over `PI_PROFILE`.Export these in the environment `ai-memory run` itself sees, or pass them with`--env` (below), not only inside a harness wrapper script. `ai-memory run`resolves the native session directory, and auto-wires hooks and MCP, from thatdiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex ad358e6b..4c1a3c08 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -1162,9 +1162,12 @@ OpenClaw distinguishes transports explicitly. Use`~/.omp/profiles/<name>/agent/mcp.json` under a named profile(`OMP_PROFILE`, or the legacy `PI_PROFILE`), or`$PI_CODING_AGENT_DIR/mcp.json` when that variable relocates the default- profile; OMP's `PI_CONFIG_DIR` renames the `~/.omp` root in each case+ profile.- Project: `.omp/mcp.json`+`PI_CONFIG_DIR` changes the `.omp` root relative to your home. An explicit+`PI_CODING_AGENT_DIR` for the default profile keeps its own path.+The current Oh My Pi package exposes the `omp` binary and native`.omp` config directories. Use `omp` (or `oh-my-pi`) for this integration;real `pi` is recognized separately and uses the generated bridge extension below.@@ -1191,8 +1194,8 @@ ai-memory install-hooks --agent omp --applyThis writes `~/.omp/agent/extensions/ai-memory-omp.ts`, which OMP discoversas a direct TypeScript extension on startup. Restart `omp` afterinstalling or changing the file. `--profile <name>` (or `OMP_PROFILE`)-targets `~/.omp/profiles/<name>/agent/extensions/`, and a named profile-ignores `PI_CODING_AGENT_DIR`, as OMP does. For the default profile,+targets `~/.omp/profiles/<name>/agent/extensions/`. Named profiles ignore+`PI_CODING_AGENT_DIR`. For the default profile,`PI_CODING_AGENT_DIR` relocates OMP's whole `~/.omp/agent` home, so theextension and `mcp.json` move to `$PI_CODING_AGENT_DIR` instead.