Skip to content

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.md
index 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.0
now write `$CODEX_HOME/config.toml`, matching `hooks.json`; `uninstall`
sweeps the legacy `~/.codex/config.toml` too, and `install-hooks` still
infers 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` pointed
installs at a blank-named directory under the working directory, and a
whitespace-only relocation variable did the same for `ai-memory run`'s
diff --git a/docs/install.md b/docs/install.md
index 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:
```bash
ai-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 --apply
OMP_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.
```bash
ai-memory install-hooks --agent pi --apply \
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 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 adapter
requires the UUID filename, header id, and canonical header `cwd` to agree
before 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. Nati
environment 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 that
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 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 --apply
This writes `~/.omp/agent/extensions/ai-memory-omp.ts`, which OMP discovers
as a direct TypeScript extension on startup. Restart `omp` after
installing 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 the
extension and `mcp.json` move to `$PI_CODING_AGENT_DIR` instead.