diff --git a/AGENTS.md b/AGENTS.md index 5ade505..5c1614e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,38 +79,47 @@ Three wrappers live happily as standalone scripts — no shared helper library y ## Adding a new harness extension -`extensions//` is the home for per-agent-harness bridges — code that -lives inside an agent runtime (pi, claude-code, kiro, …) and talks to the -mempalace MCP server. Currently only `extensions/pi/` exists. If you add -a second one (e.g. `extensions/claude-code/`), follow the same shape: +`extensions//` is the home for **bridges** — code that lives +inside an agent runtime (pi, claude-code, kiro, …) and talks to the +mempalace MCP server. Currently only `extensions/pi/` exists. If you +add a second one (e.g. `extensions/claude-code/`), follow the same +shape: 1. **One directory per harness.** Never mix harnesses in one dir. -2. **A `README.md`** covering: what it does, harness-specific install path, - debug knobs, and any gotchas (e.g. the pi `Type.Unsafe` schema passthrough). -3. **Symlink what's safe to symlink, template what the harness rewrites.** - Pi rewrites `~/.pi/agent/settings.json` at runtime — shipped as - `settings.example.json` with a `cp` instruction, not a symlink, to avoid - dirtying the repo. Whereas `mempalace.ts` and `keybindings.json` are - pure config, safe to symlink. +2. **Bridge-only scope.** This toolkit owns the mempalace-side wiring; + harness-generic config (keybindings, env loaders, settings templates) + belongs in a sibling `-toolkit` repo, following the pattern + established by [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) + and [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit). + That boundary is load-bearing for `opencode-devbox`'s slim container + path (mempalace opt-out, ~300 MB saved). +3. **A `README.md`** covering: what the bridge does, harness-specific + install path, debug knobs, and any gotchas (e.g. the pi `Type.Unsafe` + schema passthrough). May also hold the "Deploying with + mempalace" recipe since that straddles the two repos. 4. **Gate `install.sh` steps on the harness being present.** Detect via - a well-known path (pi uses `~/.pi/agent/extensions/`). Skip silently on - machines without that harness. Never force-install. -5. **Back up real files, never clobber.** If a destination exists and isn't - our symlink, `mv` it to `.bak.YYYYMMDD-HHMMSS` before linking. -6. **Probe, don't halt.** Any harness-specific env / config checks use - `warn` + `return 0`, never exit non-zero. Gate on evidence the user - actually opted into the affected path (e.g. AWS probe only fires if - `settings.json` selects `amazon-bedrock`). + a well-known path (pi uses `~/.pi/agent/extensions/`). Skip silently + on machines without that harness. Never force-install. +5. **Symlink the bridge code.** `mempalace.ts` (or equivalent) gets + symlinked into the harness's extensions directory so edits flow + through git. Back up any pre-existing real file to + `.bak.YYYYMMDD-HHMMSS` before linking. +6. **Probe for the sibling toolkit.** After installing the bridge, check + whether the harness's own base config is in place (e.g. for pi-toolkit: + `~/.pi/agent/keybindings.json` symlink, `~/.oh-my-zsh/custom/pi-env.zsh`). + Warn with a `git clone` pointer if missing. `warn` + `return 0`, never + halt. 7. **Mirror in `--uninstall`.** Every symlink this repo creates must have - a matching removal step guarded by `link_if_into_repo`. -8. **Update the root `README.md`** — add to the "What this repo contains" - list and to Setup with a one-line pointer to the extension's own README. -9. **Update this file's Structure block** to list the new `extensions//` - contents. + a matching removal step guarded by `link_if_into_repo`. Do **not** + touch sibling-toolkit-owned files — point the user at + `-toolkit/install.sh --uninstall` instead. +8. **Update the root `README.md`** — repo-contents list + Ecosystem + diagram's "Who owns what" table + Setup section's deploy summary. +9. **Update this file's Structure block** to list the new + `extensions//` contents. -See `extensions/pi/README.md` and the `install_pi_extension` / -`install_pi_keybindings` / `check_pi_settings` / `check_aws_env` functions -in `install.sh` for a full worked example. +See `extensions/pi/README.md` and the `install_pi_extension` + +`check_pi_toolkit` functions in `install.sh` for a worked example. ## Testing diff --git a/README.md b/README.md index 913255f..984fd67 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,47 @@ Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace) --- +## Ecosystem + +This repo is the memory-layer hub in a family of composable toolkits. +Each `install.sh` is independent and idempotent; install only what you +need. MemPalace can be opted out entirely (the `opencode-devbox` slim +container path exercises this). + +``` + ┌──────────────────┐ + │ myconfigs │ dotfiles: ~/.config/pi/.env, ~/.config/opencode/.env, + └────────┬─────────┘ tmux CSI-u, zsh loaders, … (git-crypt encrypted) + │ provision + ┌──────────────┼──────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────────┐ + │opencode- │ │pi-toolkit│ │ (pi/opencode │ + │ toolkit │ │ │ │ installed │ + │ │ │ │ │ upstream) │ + └─────┬────┘ └─────┬────┘ └──────────────┘ + │ │ + │ (optional) │ (optional) + └──────┬───────┘ + ▼ + ┌─────────────────┐ + │mempalace-toolkit│ ← this repo + └─────────────────┘ detects pi / opencode and installs bridges + for whichever are present +``` + +Who owns what: + +| Repo | Scope | +|---|---| +| [`myconfigs`](https://gitea.jordbo.se/joakimp/myconfigs) | Dotfiles (git-crypt encrypted). Ships `.env` files each toolkit below sources. | +| [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit) | Opencode's own shell glue (env loader for `~/.config/opencode/.env`). No mempalace dep. | +| [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) | Pi's own base config (keybindings, env loader, `settings.example.json`). No mempalace dep. | +| **`mempalace-toolkit` (this)** | Memory layer. Mining wrappers in `bin/`, `opencode-mempalace-bridge` skill, pi↔mempalace MCP extension. Probes for the other toolkits' artifacts; installs bridges where relevant. | +| [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox) | Docker containers that compose any subset via independent `install.sh` invocations. | + +--- + ## Why this exists MemPalace is the agent memory layer. Its stock CLI has two gaps that bite on a machine running opencode with a docs-first palace policy: