Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(desktop): research notes for desktop-app support (RFC #878)
AkitaOnRailsd690cabdb4d4
diff --git a/AGENTS.md b/AGENTS.mdindex 8d20ace2..6c0e8f06 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -624,3 +624,8 @@ Additional boundary rules:agent-to-agent inbox/queue and the on-start hot-context notice.- [`docs/companion-crates.md`](docs/companion-crates.md) — boundary foroptional companion projects (e.g. the importer).+- [`docs/desktop/`](docs/desktop/) — research notes and phased plan for+ GUI/desktop-app support (Claude Desktop, Codex desktop, Antigravity IDE,+ ChatGPT/Grok desktop, Zed): verified per-app mechanics, capture/dedup+ design, installer + CLI coexistence. Reconciles RFC #878; read before+ any desktop-capture or tray/installer work.diff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.mdnew file mode 100644index 00000000..c0556a1f--- /dev/null+++ b/docs/desktop/antigravity.md@@ -0,0 +1,100 @@+# Antigravity IDE (research notes)++> Research for RFC #878. Verified against official docs at+> antigravity.google and the local install. The IDE is closed source+> (Windsurf/VS Code fork); its agent stack shares `~/.gemini` with the+> Antigravity CLI (successor to Gemini CLI).++## Product shape (as of 2026-10)++Google ships **Antigravity 2.0** (the desktop agent app), the **Antigravity+IDE** (standalone Windsurf-derived editor), the **Antigravity CLI** (`agy`),+and an SDK, all documented at <https://antigravity.google/docs/>. The local+machine runs the IDE (`/usr/share/applications/antigravity-ide.desktop`,+`antigravity-ide-url-handler.desktop`, Electron/VS Code profile at+`~/.config/Antigravity IDE/` — `User/globalStorage/state.vscdb`,+`workspaceStorage`, `languagepacks.json` confirm the VS Code fork layout).+`~/.gemini/` exists locally with `antigravity-cli/` and `antigravity-ide/`+subdirs plus `config/`, `settings.json`, `oauth_creds.json`.++## MCP client support — yes, store-backed and file-configurable++Official: <https://antigravity.google/docs/mcp/>++- Global config: **`~/.gemini/config/mcp_config.json`**; workspace config:+ **`.agents/mcp_config.json`** in the project root (same file for 2.0, CLI,+ and IDE).+- Schema: `mcpServers` object; stdio entries use `command`/`args`/`env`/+ `cwd`; remote entries use **`serverUrl`** (not `url`/`httpUrl`) ++ `headers`/`authProviderType`/`oauth`. Optional per-server `disabled`,+ `disabledTools`.+- Auth: Google ADC (`authProviderType: "google_credentials"`), OAuth (DCR+ automatic, or manual `clientId`/`clientSecret` with redirect+ `https://antigravity.google/oauth-callback`), tokens at+ `~/.gemini/antigravity/mcp_oauth_tokens.json`.+- IDE GUI: agent side panel → … → **MCP Servers** (MCP Store + "View raw+ config" edits the same `mcp_config.json`). CLI: `/mcp` overlay.+- Permission model keys: `mcp(server/tool)`, `mcp(server/*)`, `mcp(*)`.+- ai-memory status today: `install-mcp --client antigravity-cli` writes this+ file (repo `docs/mcp-install.md`). An HTTP ai-memory server fits the+ `serverUrl` entry shape directly.++## Lifecycle hooks — YES (the standout alongside Claude/Codex/Cursor)++Official: <https://antigravity.google/docs/hooks/>++- Config: workspace **`.agents/hooks.json`** or global+ **`~/.gemini/config/hooks.json`** (both read by 2.0, CLI, and IDE);+ plugin-bundled hooks also supported.+- Events: `PreToolUse`, `PostToolUse` (matcher = tool name regex:+ `run_command`, `view_file`, `write_to_file`, `replace_file_content`,+ `grep_search`, `invoke_subagent`, …), `PreInvocation`, `PostInvocation`+ (around each model call), `Stop`.+- Payload (stdin JSON, camelCase): `conversationId`, `workspacePaths`,+ **`transcriptPath`**, `artifactDirectoryPath`, `modelName`, plus+ `toolCall`, `stepIdx`, etc. Handlers are shell commands with a `timeout`+ (default 30s).+- **Crucially, the payload names the transcript file**:+ `<app_data_dir>/brain/<conversationId>/.system_generated/logs/transcript.jsonl`+ where `<app_data_dir>` = `~/.gemini/antigravity` (2.0),+ `~/.gemini/antigravity-cli` (CLI), **`~/.gemini/antigravity-ide` (IDE)**.++**Consequence for ai-memory:** `install-hooks --agent antigravity-cli` writes+`~/.gemini/config/hooks.json`, which the **IDE also loads** — so global+capture likely already extends to IDE sessions, with the IDE distinguishable+by its `transcriptPath` prefix (`antigravity-ide/brain/...`). Differences to+handle: no `SessionStart`/`SessionEnd` events (session boundaries must be+inferred from PreInvocation/Stop), and `cwd` comes as `workspacePaths[]`+rather than a single `cwd`. Needs a live verification pass on the IDE.++## Transcript store (local, readable)++`~/.gemini/antigravity-ide/brain/<conversationId>/` per conversation:+`transcript.jsonl` + artifacts (per hooks doc). A watcher/poll importer over+`brain/*/` is therefore possible as a fallback capture path.++## Plugin/extension surface++Docs list Skills, Rules, custom subagents, hooks, **Sidecars**, a+Marketplace, and an SDK; IDE extensions for VS Code/JetBrains/Zed/Xcode also+exist. (Not yet researched in depth; the marketplace/plugin format was not+needed for capture conclusions.)++## Open-source status++- Antigravity IDE: **closed** (Windsurf/VS Code-derived binary).+- Antigravity CLI (`agy`): closed binary per repo docs ("built in Go",+ per ai-memory's `docs/mcp-install.md`); Gemini CLI+ (`google-gemini/gemini-cli`) is the open ancestor, and a "GCLI migration"+ doc exists. Not cloned (nothing directly informative beyond docs).+- SDK: documented Python SDK (<https://antigravity.google/docs/sdk/overview/>).++## Sources++- <https://antigravity.google/docs/mcp/>, <https://antigravity.google/docs/hooks/>,+ <https://antigravity.google/docs/cli/overview/>+- Local: `~/.config/Antigravity IDE/` (VS Code-fork layout,+ `User/globalStorage/state.vscdb` — no MCP keys configured yet),+ `~/.gemini/` (config root shared by CLI + IDE),+ `/usr/share/applications/antigravity-ide*.desktop`+- ai-memory repo: `docs/mcp-install.md` (Antigravity CLI section)diff --git a/docs/desktop/capture-and-dedup.md b/docs/desktop/capture-and-dedup.mdnew file mode 100644index 00000000..3a8cff23--- /dev/null+++ b/docs/desktop/capture-and-dedup.md@@ -0,0 +1,134 @@+# Capture & dedup without lifecycle hooks — and what actually has hooks (research)++> Research for RFC #878. Findings that drive the design; see per-app files+> for sources. Rule from RFC #878 that still holds: everything entering the+> store goes through `sanitize()` → `/hook` or `/hook/batch`; never a direct+> wiki/DB write.++## 1. Revised capture map++RFC #878's core claim ("no clean automatic-capture story for closed desktop+apps; Cursor is the exception") needs revision after this research:++| Surface | Capture mechanism | Effort |+| --- | --- | --- |+| Claude Desktop **Code/Cowork** | Already captured: desktop runs Claude Code with user `~/.claude/settings.json` → ai-memory hooks fire (`agent=claude-code`, cwd = scratch workspace). **Zero new code.** | 0 |+| Codex desktop (Codex mode) | Same host config as CLI (`~/.codex/hooks.json`) → hooks expected to fire in-app. **Verify live; then zero code.** | verify |+| Antigravity IDE / 2.0 / CLI | Native hooks (`~/.gemini/config/hooks.json` + `.agents/hooks.json`); payload has `conversationId`, `transcriptPath`, `workspacePaths[]`, `toolCall`. Map to `/hook` observations. ai-memory already ships `install-hooks --agent antigravity-cli`; IDE reads the same global file. | adapter polish |+| Zed (ACP + terminal agents) | Agent's own hooks; Zed transparent. | 0 |+| Claude Desktop **Chat tab**, hosted ChatGPT chat, Grok Bot | No hooks, no local store → model-discretion MCP tool calls (option a) and/or explicit capture tool. | RFC Phase 1 |+| Hosted ChatGPT plugins | Remote-only; needs published plugin + reachable server. | new surface |++### What the MCP server can see server-side (all apps)++ai-memory *is* the MCP server, so on any MCP-connected app we observe:+tool calls (name + args + results), call timestamps, and — through the MCP+session — nothing else. We do **not** see chat turns, prompts, or model+output. Practical consequences:++- Server-side observation is enough for **usage telemetry** (which tools an+ app's model actually calls) and for **recall-effectiveness** signals, not+ for conversation capture.+- It is *also* enough to implement an explicit capture primitive the model+ can be instructed to call (RFC #878 Phase-1 `memory_capture_conversation`+ idea): on apps without any hook surface this is the only in-band path,+ and its quality is bounded by the model's willingness to summarize.++### Local-store watchers (option c) — status++Now concrete per app (paths verified locally unless noted):++- `~/.claude/projects/<munged-cwd>/<session>.jsonl` — Claude Code-family+ transcripts (desktop Code/Cowork included). Watcher optional: hooks+ already cover it; a watcher adds value only for hookless flows (e.g.+ user disabled hooks).+- `~/.codex/sessions/**/rollout-*.jsonl` + `~/.codex/history.jsonl` — Codex.+- `~/.gemini/antigravity{,-ide,-cli}/brain/<conversationId>/**/transcript.jsonl`+ — Antigravity (per hooks doc; not yet verified locally — no IDE chats on+ the machine).+- Zed native agent: internal DB in Zed's data dir — **do not** build on it+ (unstable, version-fragile); rely on ACP agents instead.+- Claude Chat tab / hosted ChatGPT / Grok Bot: **no local store** — watcher+ class does not apply.++A watcher/importer remains the importer-envelope (`/hook/batch`) pattern+from `companions/ai-memory-importer`; keep it out of core (RFC #878 rule).++## 2. Session identity & dedup design++### Claude CLI ↔ Desktop (the case that prompted this)++Verified mechanics (see `claude-desktop.md`):++- Desktop Code sessions **are** Claude Code sessions: one `session_id`+ (CLI UUID). `/desktop` and `claude --desktop --resume <id>` move the same+ id across surfaces. ai-memory's `(agent=claude-code, session_id)` key+ therefore sees **one session**, no dedup needed.+- Desktop Cowork spawns **new** CLI sessions under ephemeral scratch cwds+ (`~/.config/Claude/scratch-workspaces/<acct>/<org>/scratch-YYYY-MM-DD-hex`).+ Two effects to design for:+ 1. **Project fragmentation**: every scratch dir becomes its own+ auto-named project. Today that means a stream of one-off projects.+ Options (product decision, not research):+ - (a) detect the scratch-workspace path prefix in scope resolution and+ route to a single `desktop/claude-cowork` project (keeps memory in+ one pool); or+ - (b) leave per-scratch projects but tag them `claude-desktop` via+ session metadata for filtering.+ The desktop-side record (`~/.config/Claude/claude-code-sessions/.../+ local_*.json`) provides `title`, `createdAt`, account/org and the+ `local_* ↔ cliSessionId` mapping if we want to enrich/label — but it is+ an implementation detail of a closed app; treat as optional hint, not+ a dependency (it can move without notice).+ 2. **Bridging id exposure**: the desktop id (`local_*`) never reaches+ hooks, so no collision risk with the CLI UUID.+- Live-only correlation: `~/.claude/sessions/<pid>.json` gives+ `entrypoint: claude-desktop` + `hostSessionId` while a process runs. Not+ archival; useful at most for a tray app's "current desktop sessions" view.+- The cc-socks Unix sockets (`/run/user/<uid>/cc-socks/<pid>.sock`) are an+ internal IPC of the closed app — **do not** build on them.++### Codex++One Codex host per user: CLI + desktop + IDE extension share `~/.codex`+(config **and** session rollout store). Session ids are the rollout UUIDs;+`(agent=codex, session_id)` is already correct, and a session started in+the desktop app is distinguishable only by content/absence of TUI markers —+no id-level split. Hosted ChatGPT/Codex-cloud sessions are cloud ids that+never touch the local store; if cloud-side capture ever matters it arrives+via export/API, mapped as a *separate* agent kind (e.g. `codex-cloud`) to+avoid double-counting with local rollouts.++### Antigravity++`conversationId` (UUID) is the session key, identical across IDE/CLI/2.0+for the same conversation; the surface is distinguishable by the+`transcriptPath` prefix (`antigravity-ide/` vs `antigravity-cli/` vs+`antigravity/`). Map to ai-memory: `agent=antigravity`, session_id =+`conversationId`, cwd = `workspacePaths[0]` (fallback: last path; the+payload has no scalar `cwd`). Hook set lacks SessionStart/SessionEnd —+derive session boundaries from first/last observation timestamps per+conversation id (ai-memory sessions are already built from observation+streams, so a Stop-hook flush marker is enough; optional).++### General rule++Dedup key stays `(agent, session_id)`; **surface variants of one agent+ecosystem that share an id space stay one agent kind** (claude-code covers+CLI+desktop; codex covers CLI+desktop+IDE ext; antigravity covers+IDE+CLI+2.0). Where a closed app keeps its own id (desktop `local_*`),+never invent capture from it — treat as metadata only.++## 3. Open questions++1. Do Codex hooks fire for desktop-app sessions? (live test; if no, a+ `~/.codex/sessions` watcher is the fallback for desktop capture.)+2. Does Antigravity IDE honor `~/.gemini/config/hooks.json` in practice, and+ does `workspacePaths` ever contain >1 path on this setup? (live test)+3. Claude Desktop Chat tab: is any local conversation cache planned+ (desktop extensions/plugins evolve fast)? Re-check quarterly; not+ buildable today.+4. Grok Bot `mcpBoxServers` entry format — reverse-engineer only if the+ product gains traction with users; no docs.+5. Scope for scratch-workspace sessions: single `desktop/claude-cowork`+ pool vs per-scratch projects (product decision; affects auto-scope).diff --git a/docs/desktop/chatgpt-desktop.md b/docs/desktop/chatgpt-desktop.mdnew file mode 100644index 00000000..a350276e--- /dev/null+++ b/docs/desktop/chatgpt-desktop.md@@ -0,0 +1,75 @@+# ChatGPT desktop (research notes)++> Research for RFC #878. Two different things get called "ChatGPT desktop"+> in late 2026; both are covered. The local machine has no official ChatGPT+> desktop app — its `ChatGPT.desktop` is an Omarchy webapp launcher+> (`Exec=omarchy-launch-webapp https://chatgpt.com/`), i.e. a browser+> wrapper, not the app. Research therefore rests on official docs.++## 1. The ChatGPT desktop app (Codex host) — official++As of 2026-10 OpenAI ships **one desktop app** that hosts both ChatGPT+(chat/Work) and **Codex** (coding agent): "Download ChatGPT for macOS,+Windows, or Linux… Choose ChatGPT or Codex. In ChatGPT, use the toggle above+the composer to select Chat or Work" (<https://developers.openai.com/codex/app>).+All MCP/hook mechanics of this app are covered in+[`codex-desktop.md`](codex-desktop.md) — summary:++- **MCP: yes** (stdio + streamable HTTP), configured in+ `~/.codex/config.toml` `[mcp_servers.*]` or Settings → MCP servers; config+ shared with Codex CLI and IDE extension.+- **Lifecycle hooks: yes** (Codex hooks framework, `~/.codex/hooks.json`) on+ the Codex side; whether hooks fire for Chat-mode conversations is **not+ documented** — Chat/Work conversations are cloud-thread-shaped and the+ hooks doc speaks of Codex sessions/turns. Treat Chat-mode auto-capture as+ unavailable; Codex-mode capture as available (verify live).+- **Transcripts**: Codex-mode sessions land in `~/.codex/sessions/`+ rollout JSONL on the Codex host. Chat-mode conversations are cloud-stored;+ no local transcript store documented.++## 2. ChatGPT web/chat surfaces — connectors (remote MCP only)++- "ChatGPT web can use remote MCP-backed tools supplied by plugins. Local+ Codex clients can also connect directly to MCP servers… ChatGPT web+ doesn't read local Codex configuration files"+ (<https://developers.openai.com/codex/extend/mcp>).+- The extension surface is **plugins**: MCP server (+ optional UI, events,+ skills) published to the ChatGPT plugin directory+ (<https://developers.openai.com/plugins>). Auth is OAuth/Sign-in-with-+ ChatGPT; no stdio/local servers in hosted Chat.+- Plugins/connections are administered per workspace for ChatGPT Work+ (<https://developers.openai.com/codex/enterprise/apps-and-connectors>).+- **Implication for ai-memory:** an ai-memory *plugin* (hosted remote MCP+ pointing at a user-run server) is the only sanctioned path into hosted+ ChatGPT chat — same shape as RFC #878's "remote-only connectors"+ conclusion. A local loopback ai-memory server cannot be reached from+ hosted Chat; a tunnel (e.g. OpenAI's "Secure MCP Tunnel" docs exist at+ <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>) or a+ hosted deployment would be required. Not researched further here.++## Linux status++The official app now supports Linux+(<https://developers.openai.com/codex/linux/linux-app>); historically Linux+users only had web/wrappers (as on this machine). The AUR `codex-desktop`+family (distsystem fork) predates/parallels official Linux availability —+see [`codex-desktop.md`](codex-desktop.md).++## Capture / dedup notes++- Chat-mode: no hooks, no local transcripts → model-discretion memory tool+ calls only (option (a) in RFC #878) unless a hosted plugin is built.+- Codex-mode in the desktop app: same store/session identity as Codex CLI+ (`session_id` from hooks/rollouts under `~/.codex/sessions/`), so+ ai-memory's `(agent=codex, session_id)` keying applies unchanged.+- No documented CLI↔desktop session handoff (unlike Claude's `/desktop`).++## Sources++- <https://developers.openai.com/codex/app>,+ <https://developers.openai.com/codex/extend/mcp>,+ <https://developers.openai.com/codex/linux/linux-app>,+ <https://developers.openai.com/plugins>,+ <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>+- Local: `~/.local/share/applications/ChatGPT.desktop` (Omarchy webapp+ launcher — proves no official app installed here)diff --git a/docs/desktop/claude-desktop.md b/docs/desktop/claude-desktop.mdnew file mode 100644index 00000000..048ab3a2--- /dev/null+++ b/docs/desktop/claude-desktop.md@@ -0,0 +1,157 @@+# Claude Desktop (research notes)++> Research for RFC #878. Verified against official docs and the local Linux+> install on the research machine (Omarchy/Arch, `~/.config/Claude`). Closed+> source. Facts below cite either a URL or a local path found on this machine.++## Product shape (as of 2026-10)++One Electron app, three tabs: **Chat** (claude.ai consumer chat), **Cowork**+(long-running agentic work / Dispatch), **Code** (Claude Code sessions).+Officially on macOS and Windows; **Linux is an official beta** (apt/.deb for+Ubuntu and Debian — <https://code.claude.com/docs/en/desktop>,+<https://code.claude.com/docs/en/desktop-linux>). The local machine runs the+Linux build (`/usr/share/applications/com.anthropic.Claude.desktop`,+Electron profile at `~/.config/Claude/`).++The **Code tab runs the same Claude Code engine as the CLI**:+"Desktop runs the same underlying engine with a graphical interface… They+share configuration and project memory via CLAUDE.md files" and "The desktop+app reads the same settings files as the CLI"+(<https://code.claude.com/docs/en/desktop>).++The desktop app ships and auto-manages its own Claude Code CLI copy:+`~/.config/Claude/claude-code/2.1.280/claude` (+ `.payload`, `.verified`+marker files) — found locally.++## MCP client support++Two distinct MCP surfaces:++1. **Chat tab (consumer app)** — local stdio MCP servers via the classic+ config file `claude_desktop_config.json` under an `mcpServers` key, plus+ remote HTTPS connectors configured in-app ("Connectors"). Config paths:+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json` (or the MSIX+ AppContainer path — ai-memory's `install-mcp --client claude-desktop`+ already detects both)+ - Linux: `~/.config/Claude/claude_desktop_config.json` (**verified+ locally**; the file exists with a `preferences` object — the Linux beta+ reuses the same file). Note ai-memory's own `docs/mcp-install.md` still+ says "Linux: not officially distributed by Anthropic" — that is now+ outdated versus the official Linux beta and should be updated in a+ follow-up docs PR.+ - Source: <https://modelcontextprotocol.io/quickstart/user> (mac/win+ paths), local file inspection, ai-memory `docs/mcp-install.md`.+ - Local MCP logs: `~/Library/Logs/Claude/mcp*.log` (mac),+ `%APPDATA%\Claude\logs` (win) — same source.+2. **Code tab (Claude Code host)** — the same MCP configuration the CLI uses:+ `~/.claude.json` (local/user scope), `.mcp.json` (project scope), settings+ files, and **plugins** (a plugin can bundle MCP servers + hooks; the+ desktop app has a plugin browser). Connectors in the prompt "+" menu are+ "MCP servers with a graphical setup flow"+ (<https://code.claude.com/docs/en/desktop#connect-external-tools>).+ Transports: stdio, SSE, HTTP (streamable), WebSocket, and an SDK-only+ in-process `type: "sdk"` reserved for host applications such as the+ desktop app (<https://code.claude.com/docs/en/mcp>).++Remote per-session MCP servers also appear in desktop session state —+`~/.config/Claude/claude-code-sessions/<account>/<org>/local_*.json` contains+a `remoteMcpServersConfig` list (verified locally; two remote servers incl.+Anthropic's own Docs MCP).++**Desktop Extensions (`.mcpb`)** were announced (Sept 2025) as a one-click+bundle format for local MCP servers. Current official docs route one-click+extensibility through **plugins** (`/plugin install`, marketplaces) rather+than `.mcpb`; the RFC's `.mcpb` assumption needs re-validation before any+Phase-1 work. Ambiguous — flagged rather than guessed.++## Lifecycle hooks / capture surface++- **No push hooks in the Chat/Cowork tabs.** Capture for consumer-chat+ conversations stays model-discretion (memory tool calls) — unchanged from+ RFC #878's conclusion.+- **The Code tab is full Claude Code**, and it reads the user's+ `~/.claude/settings.json` — where ai-memory's hooks are already installed+ (verified locally: `hooks.SessionStart` →+ `ai-memory ... hook --event session-start --agent claude-code ...`).+ Therefore **ai-memory already captures desktop Code sessions today**, keyed+ `agent=claude-code`, `session_id=<CLI UUID>`, `cwd=<session workspace>`.+- Cowork/local-agent sessions run in per-session scratch workspaces:+ `~/.config/Claude/scratch-workspaces/<account>/<org>/scratch-<date>-<hex>/`+ (verified locally), which show up in `~/.claude/projects/` as ordinary+ per-directory projects (verified: several+ `-home-...-Claude-scratch-workspaces-...` project dirs).+- Consumer-chat transcripts are **cloud-stored**; no stable local transcript+ store for the Chat tab. Code-tab transcripts are the standard+ `~/.claude/projects/<munged-cwd>/<session-uuid>.jsonl` files.++## Session bridging (CLI ↔ Desktop) — verified mechanism++The user report "desktop catches CLI sessions and chat continues on both" is+real and observable on this machine. Mechanism, from local artifacts:++1. **Every running `claude` process registers a live descriptor** at+ `~/.claude/sessions/<pid>.json` (verified locally). Fields include:+ - `sessionId` — the Claude Code session UUID+ - `entrypoint: "claude-desktop"` when desktop-spawned+ - `hostSessionId: "local_<uuid>"` — the desktop app's own session id+ - `cwd`, `version`, `peerProtocol`, `peerFeatures`+ (`notify_idle`, `reply_across_default_dirs`, `artifact_yield`)+ - `messagingSocketPath: /run/user/<uid>/cc-socks/<pid>.sock` — a Unix+ socket used for cross-surface messaging between desktop and CLI peers.+2. **Desktop-side session records** live at+ `~/.config/Claude/claude-code-sessions/<account>/<org>/local_<uuid>.json`+ (verified locally) and carry the join key:+ - `sessionId: "local_<uuid>"` (desktop id)+ - `cliSessionId: "<CLI session UUID>"` — **the same UUID as the+ `~/.claude/projects/.../<uuid>.jsonl` transcript**+ - plus `cwd`, `originCwd`, `model`, `permissionMode`, `title`,+ `remoteMcpServersConfig`, timestamps.+3. **Explicit moves**: `/desktop` inside the CLI "saves your session and+ opens it in the desktop app, then exits the CLI"; from the shell,+ `claude --desktop [--continue | --resume <session-id>]` opens an existing+ CLI session in Desktop and the **session keeps its ID**+ (<https://code.claude.com/docs/en/desktop#coming-from-the-cli>).+4. **Deep links**: `claude-cli://` URL scheme handled by+ `~/.local/share/applications/claude-code-url-handler.desktop` →+ `claude --handle-uri %u` (verified locally) — how other apps hand a+ session to Claude Code.+5. Desktop's "work across sessions" surface only sees sessions the desktop+ app itself runs (local/SSH/WSL), **not** terminal CLI or VS Code extension+ sessions; cross-session messaging can additionally reach terminal Claude+ Code sessions (same doc).++### What ai-memory's `(agent, session_id)` key sees++- A desktop Code session and the CLI session it came from (via+ `--resume`/`/desktop`) are **one session id** — capture dedups naturally.+- A desktop Cowork session is a *new* CLI session (new UUID) whose cwd is a+ fresh scratch workspace; ai-memory sees it as a claude-code session in an+ auto-named project derived from the scratch path. The desktop↔CLI mapping+ (`local_* ↔ cliSessionId`) is available on disk if we ever want to join or+ relabel desktop-originated sessions (see `capture-and-dedup.md`).+- The `entrypoint: "claude-desktop"` marker in `~/.claude/sessions/<pid>.json`+ is a reliable way to distinguish desktop-spawned sessions post-hoc while+ the process lives; it is transient (pid-keyed), not archival.++## Open-source status++- Claude Desktop app: **closed** (Electron).+- Claude Code CLI: distributed via npm/`~/.local/bin/claude`; the GitHub repo+ `anthropics/claude-code` hosts docs/issues, not full open source. The+ desktop app's bundled copy (`~/.config/Claude/claude-code/2.1.280/claude`)+ is the same distribution.++## Sources++- <https://code.claude.com/docs/en/desktop> (desktop app reference, CLI+ comparison, `/desktop`, settings sharing)+- <https://code.claude.com/docs/en/mcp> (Claude Code MCP reference)+- <https://modelcontextprotocol.io/quickstart/user> (claude_desktop_config+ paths, mcp logs)+- <https://code.claude.com/docs/en/desktop-linux> (Linux beta)+- Local: `~/.config/Claude/` (config, sessions, scratch workspaces, bundled+ CLI), `~/.claude/sessions/`, `~/.claude/projects/`,+ `~/.local/share/applications/claude-code-url-handler.desktop`+- ai-memory repo: `docs/mcp-install.md` (claude-desktop section), RFC #878.diff --git a/docs/desktop/codex-desktop.md b/docs/desktop/codex-desktop.mdnew file mode 100644index 00000000..c2583d1e--- /dev/null+++ b/docs/desktop/codex-desktop.md@@ -0,0 +1,124 @@+# Codex desktop (the ChatGPT desktop app) (research notes)++> Research for RFC #878. Verified against official docs, the open-source CLI+> repo (cloned to `~/Projects/_desktop-research/codex-research`), the Linux+> repackaging project (cloned to+> `~/Projects/_desktop-research/codex-desktop-linux-research`), and the local+> install.++## Product shape (as of 2026-10)++OpenAI has merged Codex into the **ChatGPT desktop app**: "Download ChatGPT+for macOS, Windows, or Linux… Choose ChatGPT or Codex"+(<https://developers.openai.com/codex/app>). Officially supported on+**macOS, Windows, and Linux** (docs at+<https://developers.openai.com/codex/linux/linux-app>). The app is Electron;+the local machine runs the community Linux repackaging+`codex-desktop-linux` (AUR `codex-desktop-linux` / originally+`ilysenko/codex-desktop-linux`, maintained here under the `distsystem` fork)+which **converts the upstream macOS `Codex.dmg` into Linux .deb/.rpm/pacman+packages** — i.e. the app itself is closed; the wrapper is open.++Local artifacts: `/usr/share/applications/codex-desktop.desktop`+(`Exec=... /usr/bin/codex-desktop`), Electron profiles at `~/.config/Codex`+(release) and `~/.config/Codex (Dev)` (dev build), `~/.config/codex-desktop`+only holds `electron-flags.conf`.++The desktop app drives the **same Codex core** as the CLI — the open-source+repo contains `codex-rs/app-server`, `app-server-protocol`,+`app-server-daemon`, `app-server-transport` crates+(`~/Projects/_desktop-research/codex-research/codex-rs/`), and docs at+<https://developers.openai.com/codex/app-server> describe the App Server+protocol; <https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server>+documents running your own app-server against the ChatGPT plan.++## MCP client support — shared config with the CLI++"The ChatGPT desktop app, Codex CLI, and IDE extension support MCP servers+and **share MCP configuration for the same Codex host**"+(<https://developers.openai.com/codex/extend/mcp>):++- Config file: `~/.codex/config.toml`, `[mcp_servers.<name>]` tables;+ project scope `.codex/config.toml` (trusted projects only). **Verified+ locally**: `~/.codex/config.toml` already contains+ `[mcp_servers.ai-memory] url = "http://192.168.0.90:49374/mcp"` (remote+ streamable HTTP — works with the desktop app, no Node/npx needed).+- Desktop app GUI: Settings → MCP servers → Add server (STDIO or Streamable+ HTTP); `/mcp` in the composer lists servers.+- CLI: `codex mcp add <name> -- <command>` / `codex mcp list`.+- Transports: stdio (command/args/env/cwd/env_vars) and streamable HTTP+ (`url`, `bearer_token_env_var`, `http_headers`, `env_http_headers`,+ `http_headers_helper`), OAuth incl. CIMD/DCR and ChatGPT session auth.+ ai-memory's loopback HTTP + optional bearer token maps directly onto this.+- Server `instructions` field is read as server-wide guidance (keep first+ 512 chars self-contained) — relevant for how ai-memory's tool-routing+ guidance is surfaced in Codex.++## Lifecycle hooks — full Claude-Code-style model, in core++Codex has a native lifecycle-hooks framework+(<https://developers.openai.com/codex/hooks>), confirmed in source+(`codex-rs/hooks/`, events `user_prompt_submit.rs`, `declarations.rs`):++- Events: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`,+ `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`,+ `SubagentStart`, `SubagentStop`, `Stop`, `Interrupt`.+- Config: `~/.codex/hooks.json` (or inline `[hooks]` in `config.toml`),+ repo `<repo>/.codex/hooks.json`, plugin-bundled hooks. **Verified+ locally**: ai-memory already writes `~/.codex/hooks.json` with+ SessionStart/UserPromptSubmit/PreToolUse/PostToolUse command hooks calling+ `ai-memory hook --event ... --agent codex --server-url ...`.+- Hook stdin includes `session_id`, `transcript_path`, `cwd`,+ `hook_event_name`, `model` — everything ai-memory's capture needs.+- Trust review: non-managed hooks must be trusted once (`/hooks` in the+ TUI); trust is recorded against the hook's hash.+- Handlers can be `command` or `mcp_tool` (a lifecycle event can call a tool+ on a connected MCP server — an interesting future capture path).++**Open question (needs a live test):** the hooks doc does not explicitly+scope hooks to the CLI. Since the desktop app and CLI "share MCP+configuration for the same Codex host" and hooks live in the same config+layers, desktop-app Codex sessions are *expected* to fire the same hooks —+but none of the fetched pages says so in so many words. Verification test:+run a session in the desktop app with ai-memory hooks installed and watch+`/hook` observations arrive (or check `~/.codex/sessions/rollout-*.jsonl`+creation + ai-memory session list). Until then, treat as *likely, unproven*.++## Transcript store++`~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-uuid>.jsonl` (verified+locally), plus `~/.codex/history.jsonl` (prompt history keyed by+`session_id`). Same store for CLI and (expected) desktop sessions — the+desktop app is the same Codex host.++## Session bridging++No CLI↔desktop bridge equivalent to Claude's `/desktop` is documented.+CLI and desktop are separate conversation lists over the same host config;+ChatGPT web/mobile/cloud surfaces are cloud-side and do not read local+config ("ChatGPT web doesn't read local Codex configuration files",+<https://developers.openai.com/codex/extend/mcp> — web section). `dots`+(persistent agents) are cloud-orchestrated; enterprise hooks for dots are+remote MCP hooks, not local command hooks.++## Open-source status++- `openai/codex` (Apache-2.0): CLI + `codex-rs` core, **hooks crate,+ codex-mcp, app-server crates** — open.+- The ChatGPT/Codex **desktop app**: closed (Electron); Linux build only via+ the community DMG-conversion project (`ilysenko/codex-desktop-linux`,+ packaged here by `distsystem`).++## Sources++- <https://developers.openai.com/codex/app>,+ <https://developers.openai.com/codex/extend/mcp>,+ <https://developers.openai.com/codex/hooks>,+ <https://developers.openai.com/codex/linux/linux-app>,+ <https://developers.openai.com/codex/app-server>+- Clones: `~/Projects/_desktop-research/codex-research` (openai/codex @+ 5a31401, 2026-10-07), `~/Projects/_desktop-research/codex-desktop-linux-research`+- Local: `~/.codex/{config.toml,hooks.json,sessions/,history.jsonl}`,+ `~/.config/Codex/`, `~/.config/'Codex (Dev)'/`,+ `/usr/share/applications/codex-desktop.desktop` (pacman+ `codex-desktop-linux 26.707.31428`)diff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.mdnew file mode 100644index 00000000..ee55d78d--- /dev/null+++ b/docs/desktop/desktop-landscape.md@@ -0,0 +1,50 @@+# Desktop landscape — apps × capabilities (research matrix)++> Research for RFC #878 (2026-10-07). Every row is sourced in the per-app+> note (`<app>.md`). "Local verified" = confirmed from files on the research+> machine; otherwise the official-doc URL is the source.++| App | MCP client | Remote HTTP MCP | Lifecycle hooks | Local transcript store | Plugin/extension API | Open source | Session bridge to CLI |+| --- | --- | --- | --- | --- | --- | --- | --- |+| **Claude Desktop** (Chat+Cowork+Code tabs; Linux beta) | Chat tab: stdio via `claude_desktop_config.json` + GUI connectors. Code tab: full Claude Code MCP (stdio/SSE/HTTP/WS, plugins) | Yes (connectors + Code-tab http) | **Yes for Code/Cowork** — same `~/.claude/settings.json` hooks the CLI uses (local verified); none for Chat tab | Code/Cowork: `~/.claude/projects/<cwd>/<uuid>.jsonl` (local verified). Chat: cloud only | Plugins (marketplace, can bundle MCP+hooks; desktop has plugin browser); `.mcpb` desktop extensions announced 2025 — current status ambiguous | App closed; claude-code CLI distributed not-open | **Yes** — `/desktop`, `claude --desktop --resume <id>`; live registry `~/.claude/sessions/<pid>.json` (`entrypoint`, `hostSessionId`, cc-socks messaging socket); desktop record `local_* ↔ cliSessionId` |+| **Codex desktop** (= ChatGPT desktop app, macOS/Windows/Linux) | Yes — `~/.codex/config.toml` `[mcp_servers.*]` (stdio + streamable HTTP + OAuth/CIMD/DCR), Settings GUI, shared with CLI/IDE | Yes (first-class) | **Yes (core)** — `~/.codex/hooks.json`, 12 events, trust review; firing in desktop app *likely but unverified live* | `~/.codex/sessions/**/rollout-*.jsonl` + `history.jsonl` (local verified) | Plugins (bundle MCP servers + hooks, `PLUGIN_ROOT`); App Server protocol open | Codex core open (`openai/codex`); desktop app closed (Linux via community DMG repack) | None documented |+| **Antigravity IDE** (Google; 2.0 app + CLI `agy` share `~/.gemini`) | Yes — `~/.gemini/config/mcp_config.json` + `.agents/mcp_config.json`; `serverUrl` schema; ADC/OAuth; MCP Store GUI | Yes (`serverUrl` + headers) | **Yes** — `.agents/hooks.json` / `~/.gemini/config/hooks.json` (PreToolUse/PostToolUse/PreInvocation/PostInvocation/Stop; payload includes `conversationId`, `transcriptPath`, `workspacePaths`) | `~/.gemini/antigravity-ide/brain/<conversationId>/**` incl. `transcript.jsonl` (per docs) | Skills/Rules/subagents/sidecars/marketplace + SDK | IDE closed (VS Code/Windsurf fork); CLI closed; Gemini CLI is open ancestor | None documented (IDE vs CLI share config root, distinct `brain/` roots) |+| **ChatGPT desktop (hosted chat side)** | Hosted chat: remote MCP **plugins only** (no local config read) | Yes (remote plugins) | No (Chat-mode) | No local store (cloud) | Plugins (remote MCP + UI + events; OAuth/SIWC) | Closed | n/a |+| **Grok webapp launcher** (local wrapper) | n/a (browser) | unverified | n/a | n/a | n/a | n/a | n/a |+| **Grok Bot** (Cursor; native Electron agent) | Yes — MCP machinery in app.asar (`mcpBoxServers` in `~/.grokbot/settings.json`); format/docs **unverified** | unknown | No | No local transcript documented (cloud + leveldb UI state) | plugins evident (`plugin-logo-cache`) — undocumented | Closed (downloads.cursor.com) | n/a |+| **Zed** | Yes — `context_servers` in settings.json (stdio + url/OAuth); MCP extensions; forwards servers to ACP agents | Yes | No native hooks; ACP/terminal agents bring their own | Native-agent threads in Zed's DB (fragile); terminal/ACP agents use their own stores | Extension API (WASM extensions; MCP extension manifest) | **Open** (`zed-industries/zed`) | n/a (agents run in-place; no bridge needed) |++## Highlights vs RFC #878's assumptions (what changed)++1. **The capture picture improved for two ecosystems:**+ - **Claude Desktop's Code/Cowork tabs are literally Claude Code** — hooks+ in `~/.claude/settings.json` already capture them (`agent=claude-code`,+ scratch-workspace cwd). RFC #878 classed Claude Desktop wholesale as+ "no hook/event surface"; that is only true of the Chat tab.+ - **Antigravity (IDE included) has first-class lifecycle hooks** with+ `transcriptPath` in every payload — a full auto-capture target the RFC+ didn't evaluate (it listed Cursor as the only hook-bearing desktop+ target).+2. **Codex is now the ChatGPT desktop app** with shared `~/.codex` config:+ one `install-mcp`/`install-hooks` write serves CLI + desktop + IDE+ extension (desktop-app hook firing needs one live verification).+3. **Official Linux desktop builds now exist** for Claude Desktop (beta) and+ the ChatGPT/Codex app — ai-memory's `docs/mcp-install.md` "Linux: not+ officially distributed" note for claude-desktop is stale.+4. **Grok Bot is a Cursor product** (not xAI) with embedded MCP support but+ no public docs — opportunistic, not plannable.+5. Remote/streamable-HTTP MCP is now the norm across Codex/Antigravity/Zed/+ Claude(Code) — a loopback ai-memory HTTP server needs **no npx shims** on+ any researched app except legacy Claude-Desktop-Chat stdio config.++## Ordered capture opportunity (auto-capture without new product code)++1. Claude Desktop Code/Cowork — works today via existing hooks.+2. Codex desktop (verify hooks fire in app) — works via existing+ `~/.codex` hooks if verified.+3. Antigravity IDE — via existing `~/.gemini/config/hooks.json` (agent+ mapping/`workspacePaths` handling + verification needed).+4. Zed — via ACP/terminal agents' own hooks (nothing to build).+5. Chat tab / hosted ChatGPT / Grok Bot — model-discretion only (MCP tools);+ hosted ChatGPT additionally needs a published plugin to reach a+ user-run server at all.diff --git a/docs/desktop/grok-desktop.md b/docs/desktop/grok-desktop.mdnew file mode 100644index 00000000..909aec28--- /dev/null+++ b/docs/desktop/grok-desktop.md@@ -0,0 +1,73 @@+# Grok desktop surfaces (research notes)++> Research for RFC #878. "Grok desktop" on this machine is two different+> things, both verified locally: (1) a browser webapp launcher for grok.com,+ and (2) **Grok Bot**, a real native desktop agent from Cursor. xAI's own+> official desktop app status is also noted.++## 1. Grok webapp launcher (local `Grok.desktop`)++`~/.local/share/applications/Grok.desktop` →+`Exec=omarchy-launch-webapp https://grok.com/` — an Omarchy browser wrapper,+not a native app. Nothing to integrate beyond grok.com's own web features+(remote MCP support on grok.com is **unverified** — xAI docs were not+fetched; do not assume).++## 2. Grok Bot — Cursor's desktop agent (native, closed)++`/usr/share/applications/grok-bot.desktop` → `/usr/bin/grok-bot`, pacman+package `grok-bot-bin 0.66.0-1` (AUR; local install). Key verified facts:++- **Distributed by Cursor**: the AUR PKGBUILD pulls+ `https://downloads.cursor.com/grokbot/stable/<commit>/linux/x64/grok-bot_<ver>_amd64.deb`;+ package URL/keywords say cursor.com; license `LicenseRef-Proprietary`;+ installs to `/opt/Grok Bot` (Electron). Formerly/probably codenamed+ "sand" (`provides=sand`, `sand-*` config files). AUR:+ <https://aur.archlinux.org/packages/grok-bot-bin>.+- **Config home**: `~/.grokbot/` (asar strings `.grokbot`,+ `.grokbot-data-root-v1`; verified `~/.grokbot/settings.json` locally) and+ Electron profile at `~/.config/Grok Bot/` (Local Storage leveldb, sentry,+ `dune-reliability` telemetry, `Partitions`, `attachment-image-cache`,+ `plugin-logo-cache`).+- **MCP support: yes, embedded.** `strings /opt/Grok Bot/resources/app.asar`+ shows full MCP machinery (`mcpServers`, `mcpConfigJson`, `McpServer`,+ `McpExec`, `McpAccount`, `mcp-app`, `McpCustomInstructions`,+ `mcpDisabledToolsByServerId`, …), and `~/.grokbot/settings.json` has+ `mcpBoxServers: []`, `mcpCustomInstructions`,+ `mcpCustomInstructionsByServerId`, `mcpDisabledToolsByServerId` keys+ (empty — user hasn't configured any). "Box servers" suggests MCP servers+ run inside Grok Bot's sandboxed "boxes". **No public official docs found**+ (cursor.com product pages not fetched — Grok Bot appears to be+ invite/rollout-gated); config format and whether stdio, remote, or both+ are supported is **unverified**. Next step if pursued: add an MCP entry+ via the app UI and diff `~/.grokbot/settings.json`.+- **Local-exec daemon**: `~/.grokbot/local-exec-daemon.log`,+ `local-exec-supervisor.json`, `local-exec-daemon-credential.json`,+ `gateway-descriptor.json` — the agent executes tasks locally through a+ supervised daemon (relevant if we ever need to coexist with it; not an+ integration surface).+- **No lifecycle-hook surface** documented or evident; no transcript store+ documented. Conversation data appears cloud-side (leveldb holds UI state+ only). Capture options collapse to model-discretion via MCP tools — same+ as RFC #878's closed-app bucket.++## 3. xAI official desktop app++Not verified. No local install; no official docs fetched. Grok Build CLI+(xAI's coding CLI) is a *different* product — ai-memory already supports it+(`install-mcp --client grok`, `install-hooks --agent grok`, repo+`docs/mcp-install.md`). Keep the two separate in any plan.++## Open-source status++Grok Bot: **closed** (Cursor). No repo to clone. Only external artifact+inspected: the AUR PKGBUILD + local binary/asar strings.++## Sources++- <https://aur.archlinux.org/packages/grok-bot-bin> (PKGBUILD, cursor.com+ download URL, comments)+- Local: `/opt/Grok Bot/resources/app.asar` (strings), `~/.grokbot/`,+ `~/.config/Grok Bot/`, `/usr/share/applications/grok-bot.desktop`+- ai-memory repo: `docs/mcp-install.md` (Grok Build CLI section — separate+ product)diff --git a/docs/desktop/installer-and-coexistence.md b/docs/desktop/installer-and-coexistence.mdnew file mode 100644index 00000000..fa06d02c--- /dev/null+++ b/docs/desktop/installer-and-coexistence.md@@ -0,0 +1,152 @@+# Installer & CLI coexistence for a desktop companion (research)++> Research for RFC #878. What it takes to ship an `ai-memory` tray app that+> a non-developer can install, and how it coexists with an existing+> `ai-memory` CLI install without breaking it. Verified sources: Tauri v2+> docs (fetched 2026-10), the existing Swift companion+> (`companions/ai-memory-macos/README.md`), ai-memory repo layout+> (`packaging/`, `crates/ai-memory-cli/src/server_profiles*`, hook runner+> layout observed locally), and well-known behavior of Docker Desktop /+> Tailscale (pattern references — deep docs not fetched, treat as+> directional).++## 1. Tray-app implementation options++### Option A — Tauri v2 (recommended baseline)++- **Tray**: first-class `tray-icon` feature (`TrayIconBuilder`, menus,+ events). Linux note: tray mouse-move/enter events unsupported, but icon ++ context menu work (<https://v2.tauri.app/learn/system-tray/>).+- **Bundling the Rust binary**: sidecar/external-binary support+ (<https://v2.tauri.app/develop/sidecar/>) — the tray app can embed the+ exact pinned `ai-memory` release binary.+- **Desktop-app table stakes as plugins**: `single-instance` (avoid two+ trays), `autostart` (login launch), `updater` (signed updates),+ deep-linking (`ai-memory://`) (<https://v2.tauri.app/plugin/>).+- **Packaging matrix from one toolchain** — official distribute targets:+ Linux deb / rpm / AppImage / AUR / Flathub / Snap, macOS DMG + app bundle+ (+ pkg), Windows installer (NSIS/MSI) + Microsoft Store; per-OS signing+ guides (<https://v2.tauri.app/distribute/>).+- Cost: webview-based UI (small), Rust core is fine; maturities match our+ Rust-first stack.++### Option B — pure Rust GUI: egui + `tray-icon`++- `tray-icon` (tauri-apps org, <https://docs.rs/tray-icon>) + `muda` menus;+ egui for the settings window. Lightest stack, no webview, one binary.+- Cost: we own everything Tauri gives for free — single-instance, updater,+ signing/packaging pipelines, deep links. Only worth it if the UI stays+ trivial (menu + one settings pane) — which the Swift companion's scope+ suggests it might.++### Option C — keep Swift companion + add a Linux counterpart++- macOS: `companions/ai-memory-macos` already works (ships runtime, governs+ LaunchAgent, data dir survives app replacement, philosophy: "wrapper, not+ a second operator console").+- Linux: a counterpart would duplicate the service governance (systemd user+ unit — templates already exist in `packaging/systemd/`) with a GTK/libadw+ or Tauri menu. Two codebases for one product; the existing companion+ explicitly defers notarization/Homebrew cask, so it has not reached the+ non-dev bar yet either.++**Recommendation (research-level):** Tauri v2 for a cross-platform tray+companion that *subsumes* the Swift companion's role over time, keeping the+Swift app as the macOS-first path until parity; OR B if we commit to a+minimal menu-only surface. Decision point for RFC follow-up, not settled+here.++## 2. Packaging per OS (end-user installers)++| OS | Formats | Notes |+| --- | --- | --- |+| macOS | `.dmg` (drag-install), `.pkg`, Homebrew cask | Gatekeeper: Developer ID + hardened runtime + notarize/staple (RFC #878 cost analysis stands); Swift companion currently ships un-notarized |+| Windows | NSIS or MSI (WiX) via Tauri; winget | MSIX optional; AppContainer path quirks for Claude Desktop config already handled by `install-mcp`; Authenticode signing (RFC #878: SignPath Foundation free for OSS) |+| Linux | `.deb`, `.rpm`, AppImage; AUR (we already ship AUR assets in `packaging/aur/`); Flatpak is **problematic** (sandbox vs loopback server + hook execution into arbitrary agent configs — needs portal work; defer) | systemd user unit from `packaging/systemd/`; sysusers/tmpfiles assets exist |++## 3. Coexistence with the existing CLI (the hard constraints)++Ground truth from the repo/local machine:++- **Data dir** holds wiki + SQLite + `config.toml` + spool + models:+ `~/.local/share/ai-memory` (Linux), `~/Library/Application Support/ai-memory`+ (macOS — the Swift companion's documented default), `%LOCALAPPDATA%`+ (Windows). The desktop app MUST detect and reuse it, never fork a second+ one silently.+- **One writer, one server**: ai-memory's SQLite is single-writer-actor by+ design (repo invariants #2, #9). Two server processes on one data dir is+ forbidden — so the tray app's first job is *detection*, not spawning:+ 1. Probe the configured/default server (`GET /admin/status` on the port+ from `config.toml` / default `127.0.0.1:49374`).+ 2. Check the **`server_profiles` registry** (CLI:+ `crates/ai-memory-cli/src/server_profiles.rs` — named profiles with+ url + project roots + token, used by hooks via `--server-url`). On this+ machine the hooks point at a LAN server (`--server-url+ http://192.168.0.90:49374`) — the desktop app must respect that+ instead of assuming localhost.+ 3. Only if no reachable server: offer (a) start bundled server as a+ managed service (LaunchAgent/systemd user unit/Startup task — reuse+ `packaging/` templates), or (b) connect to remote with URL+token.+- **Hooks are decoupled from app bundles already**: hooks installed by+ ai-memory invoke `~/.local/share/ai-memory/native-runner/ai-memory` (the+ native-runner copy inside the data dir; verified in local+ `~/.claude/settings.json` and `~/.codex/hooks.json`). Replacing a desktop+ app bundle therefore never rewrites hooks or breaks capture — preserve+ this invariant: **the tray app must not move or duplicate the+ native-runner path**; at most refresh it with the user's consent.+- **Version independence**: bundled binary (in the .app/resources) and any+ system CLI can differ. Rules: the *server* version wins schema truth+ (migrations run under the single-writer server); the tray UI talks HTTP+ only (`/admin/status`, `/web`, `/api/v1`) so it degrades gracefully+ against older/newer servers; `ai-memory` CLI on PATH is never overwritten+ by the app (no symlink stomping).+- **Auto-wiring MCP configs**: reuse `install-mcp` per client (it already+ knows claude-desktop incl. MSIX paths, codex, antigravity-cli, zed, grok,+ …). The desktop app should call the same library code, show a checklist+ of detected apps, and write configs idempotently (preserve unrelated+ servers — existing behavior).++## 4. The "desktop users don't know Docker" constraint++ai-memory today is a self-contained Rust binary (bundled SQLite, vendored+libgit2) — **Docker is already optional** (`docs/install.md` ships native+packages + systemd). The tray app completes that story:++- Default path: bundled binary + local data dir + loopback bind + zero+ auth (single-user posture from `docs/install.md`).+- Team/remote path: URL + bearer token (AI_MEMORY_AUTH_TOKEN) fields in the+ tray settings → written to `server_profiles` so hooks and MCP installs+ point at the same remote.+- Anti-goal: the tray app becoming an admin console. Keep the Swift+ companion's rule — open `/web` and the config file; don't duplicate.++## 5. Comparable tools (pattern reference)++- **Docker Desktop**: bundles engine + CLI, manages the VM/service, and+ exposes `docker` CLI on PATH from the app bundle; starting the app is+ starting the service. Pattern to copy: tray == service governor, CLI+ stays first-class. Pattern to avoid: version-lock pain when the desktop+ app lags the CLI.+- **Tailscale**: menu-bar app + `tailscaled` system service + `tailscale`+ CLI; on macOS the daemon ships inside the .app with a launchd agent, and+ the CLI is a symlink into the bundle. Pattern to copy: explicit+ "connected/backend state" tray affordance; CLI/daemon version skew+ tolerated by protocol.+- **Raycast**: tray-first launcher without a bundled background *service*+ — mostly useful as UI scope reference (menu + extensions), not service+ coexistence.++(These are well-known public behaviors; not re-verified against docs in+this pass — directional only.)++## 6. Open questions++1. Tauri vs egui decision (scope of UI: menu-only vs settings panes vs+ conversation viewer).+2. Flatpak feasibility (portals for background service + host file access+ to agent configs) or skip Flatpak and ship deb/rpm/AppImage/AUR only.+3. Auto-update channel policy for the bundled server binary vs CLI-managed+ installs (Tauri updater is for the app; the embedded `ai-memory`+ sidecar needs its own update story).+4. Whether the tray app should also own `install-hooks` for detected+ agents (it is the natural place for the "enable capture" toggle).diff --git a/docs/desktop/plan.md b/docs/desktop/plan.mdnew file mode 100644index 00000000..9ced7aaa--- /dev/null+++ b/docs/desktop/plan.md@@ -0,0 +1,105 @@+# Desktop support — phased plan (research output, reconciled with RFC #878)++> This file reconciles RFC #878 (github.com/akitaonrails/ai-memory#878) with+> the findings in this directory (2026-10-07). Nothing here is scheduled+> work; each phase lists what would need to change and where the risk sits.++## What the research changed vs the RFC++RFC #878's headline — "connection is solved, capture is the crux" — still+holds, but two of its premises moved:++1. **"Most desktop chat apps expose no hook/event surface"** is now false+ for the *coding* desktop surfaces: Claude Desktop's Code/Cowork tabs are+ Claude Code with the user's hooks (captured today, zero code), Codex+ desktop shares `~/.codex` hooks config (verify live), and **Antigravity+ (IDE included) has first-class lifecycle hooks** with transcript paths+ in the payload. The truly hookless set is now: Claude Desktop Chat tab,+ hosted ChatGPT chat, Grok Bot.+2. **"Claude Desktop .mcpb bundle"** as the Phase-1 one-click route: the+ current official extension surface is **plugins** (marketplace; can+ bundle MCP servers + hooks; the desktop app has a plugin browser).+ `.mcpb` status is ambiguous in current docs — re-validate before+ building anything.++## Phase 0 — docs + verify the free wins (ship anytime)++1. Update `docs/mcp-install.md`:+ - Claude Desktop **Linux** is an official beta; document+ `~/.config/Claude/claude_desktop_config.json` (replace the "not+ officially distributed" note).+ - Add a "desktop apps" section pointing at these research notes.+2. Live verifications (machine with the apps installed):+ - [ ] Codex desktop: confirm `~/.codex/hooks.json` fires for+ desktop-app sessions (watch ai-memory observations + rollouts).+ - [ ] Antigravity IDE: confirm global `~/.gemini/config/hooks.json` is+ honored by the IDE; record `workspacePaths` shape and+ `transcriptPath` layout under `~/.gemini/antigravity-ide/brain/`.+3. Document that Claude Desktop Code/Cowork sessions already flow into+ ai-memory, including the scratch-workspace project naming behavior+ (user-facing note: expect `...-Claude-scratch-workspaces-...` projects).++## Phase 1 — Antigravity IDE capture parity (smallest new-code step)++The research's best new target — not the RFC's `.mcpb`:++- Ensure `install-hooks --agent antigravity-cli` output also satisfies the+ IDE (same global file; verify; add `.agents/hooks.json` workspace install+ option).+- Map hook payloads → `/hook` observations: agent kind `antigravity`+ (covers CLI+IDE+2.0), session = `conversationId`, cwd =+ `workspacePaths[0]`, tool events from PreToolUse/PostToolUse; session+ boundaries from PostInvocation/Stop flushes (no SessionStart/End events).+- Tests: payload-mapping unit tests against the documented schema+ (camelCase fields; `<app_data_dir>` variants per surface).++## Phase 2 — scope & dedup polish for desktop-originated sessions++- Decide scratch-workspace routing: single `desktop/claude-cowork` project+ vs per-scratch projects with a `claude-desktop` tag (see+ `capture-and-dedup.md` §2). This is the only dedup work the research+ found necessary — CLI↔Desktop handoffs keep one session id, so no+ id-level dedup layer is needed.+- Optional metadata enrichment from+ `~/.config/Claude/claude-code-sessions/**/local_*.json` (titles,+ account/org) — strictly optional, closed-app internals.++## Phase 3 — explicit capture for hookless surfaces (RFC Phase 1, adjusted)++- Tool-surface change (23-tool count, MEMORY_INSTRUCTIONS/SNIPPET_BODY,+ prompt-surface regression tests, adversarial boundary test) for an+ explicit capture tool the model calls on apps without hooks (Claude Chat+ tab, Grok Bot, hosted ChatGPT chat). Scoping per RFC: fixed+ `personal/desktop-chat` (optionally per-app) since no cwd exists.+- Grok Bot MCP entry format: only worth reverse-engineering on demand.++## Phase 4 — the non-dev tray installer (RFC Phase 2, refined)++- Tauri v2 vs egui decision, packaging matrix, and the coexistence rules in+ `installer-and-coexistence.md` (detect-before-spawn server governance,+ `server_profiles` inheritance, native-runner path stability, no PATH+ stomping).+- Signing/notarization costs as in RFC #878 (unchanged).++## Explicitly deferred / rejected++- Hosted-ChatGPT plugin (remote MCP to a user-run server): real but a new+ distribution surface; needs published-plugin review requirements+ (<https://developers.openai.com/plugins/deploy/app-review>) — separate+ RFC if demand appears.+- Watching Zed's native-agent database: fragile, version-locked; ACP+ agents already give us capture for free.+- Building on `~/.claude/sessions/<pid>.json` cc-socks IPC or Grok Bot's+ local-exec daemon: closed-app internals, unstable by definition.+- A session-id mapping/alias table keyed on desktop `local_*` ids: not+ needed given one-id sessions; revisit only if Anthropic splits ids.++## Open questions (research-level, blocking nothing)++1. Codex-in-app hook firing (Phase 0 verification).+2. Antigravity IDE honoring global hooks (Phase 0 verification).+3. `.mcpb` vs plugins for Claude Desktop one-click (re-check docs).+4. Scratch-workspace scoping product decision (Phase 2).+5. Tray stack choice + Flatpak feasibility (Phase 4).+6. Does the Claude Desktop Chat tab ever gain a local store/export? (No+ current path; re-check quarterly.)diff --git a/docs/desktop/zed.md b/docs/desktop/zed.mdnew file mode 100644index 00000000..168d5400--- /dev/null+++ b/docs/desktop/zed.md@@ -0,0 +1,83 @@+# Zed (research notes)++> Research for RFC #878. Zed is open source (cloned to+> `~/Projects/_desktop-research/zed-research`); docs at zed.dev. Local+> install verified (`~/.config/zed/settings.json`).++## Product shape++Open-source editor (Rust) with an Agent Panel supporting three agent paths+(<https://zed.dev/docs/ai/mcp>):++1. **Zed Agent** (native, built-in)+2. **External Agents** via **ACP** (Agent Client Protocol,+ <https://agentclientprotocol.com/>) — e.g. Gemini CLI, Claude Code,+ codex-acp, opencode. **Verified locally**: the user's+ `~/.config/zed/settings.json` configures `agent_servers`:+ `opencode` (`type: "registry"`), `codex-acp`, `claude-acp`.+3. **Terminal Threads** — native CLIs run in Zed's terminal with their own+ config (so a `claude`/`codex` TUI inside Zed behaves exactly like the+ CLI: ai-memory hooks fire as usual, keyed by cwd).++## MCP client support++- Config: **`context_servers`** in the Zed `settings.json` (Linux+ `~/.config/zed/settings.json` — verified locally; macOS+ `~/Library/Application Support/Zed/settings.json` per Zed docs/ai-memory+ `docs/mcp-install.md`). Entries:+ - local stdio: `{"command", "args", "env"}`+ - remote: `{"url", "headers"}`; OAuth flow prompts when no+ `Authorization` header is configured.+- GUI: Settings → AI → MCP Servers → Add Server (local/remote).+- Extensions: MCP servers can ship as Zed extensions+ (<https://zed.dev/docs/extensions/mcp-extensions>).+- Feature coverage: **Tools + Prompts only** ("Discovery, Sampling,+ Elicitation, etc." not yet supported); handles+ `notifications/tools/list_changed` (same zed.dev/docs/ai/mcp page).+- MCP servers configured in Zed are **forwarded to External Agents over+ ACP**; external agents may also read their own native MCP config+ (configuration boundaries documented at+ <https://zed.dev/docs/ai/external-agents>).+- Tool permissions: `agent.tool_permissions.default`+ (`confirm`/`allow`/`deny`), per-tool rules keyed `mcp:<server>:<tool>`.++ai-memory status today: `install-mcp --client zed` exists (repo+`docs/mcp-install.md`); remote HTTP ai-memory servers fit the `url` entry.++## Lifecycle hooks / capture surface++- **No push hooks in Zed itself** (no equivalent of Claude Code/Codex/Antigravity+ hook files). Auto-capture must come from the *agent*, not the editor:+ - Terminal Threads and ACP external agents (claude-acp / codex-acp /+ opencode) fire **their own** hooks — ai-memory captures those sessions+ through the existing per-agent hook integrations (agent kind reported by+ the CLI; session lands in the project keyed by cwd, which Zed sets to+ the workspace dir).+ - The native Zed Agent has no hook surface; its threads are stored in+ Zed's own database (source: `crates/agent`, `crates/agent_ui` in the+ clone; a poll/watch importer would be per-version fragile — same bucket+ as RFC #878 option (c), only if demand appears).++## Session identity / dedup++Zed does not sit in the session path: session ids are whatever the+underlying agent (Zed Agent / ACP server / terminal CLI) mints. For ACP+agents, ai-memory sees the agent's own session id via its hooks; a Zed+ACP-run claude-acp session and a terminal `claude` session in the same repo+are two sessions in the same project — cwd-keyed project scope already+merges them correctly. No Zed-specific dedup work identified.++## Open-source status++**Open** — github.com/zed-industries/zed (cloned, shallow, for crate+layout: `crates/agent`, `crates/agent_servers`, `crates/agent_settings`,+`crates/language_extension` etc.).++## Sources++- <https://zed.dev/docs/ai/mcp>, <https://zed.dev/docs/ai/external-agents>,+ <https://zed.dev/docs/extensions/mcp-extensions>,+ <https://agentclientprotocol.com/>+- Local: `~/.config/zed/settings.json` (`agent_servers` with opencode /+ codex-acp / claude-acp), `/usr/share/applications/dev.zed.Zed.desktop`+- Clone: `~/Projects/_desktop-research/zed-research`