Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: document install-time --project-strategy
João Matheusea29bd19aa31
diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex c75979e6..966b6e87 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -204,6 +204,8 @@ Lesson from basic-memory's v0.20 trauma: `(workspace, project, page_path)`. EvenProject resolution chain: explicit param → server's default → cwd-based heuristic (match repo root) → error.+**Install-time `project_strategy` default (#128).** `basename(cwd)` stays the v1 default, but an agent shell that `cd`s into a subdirectory and stays there silently forks the rest of the session into a phantom project named after the subdir. A `.ai-memory.toml` marker with `project_strategy = "repo-root"` fixes this (#16, #23, #111) but needs a marker in (or above) every repo; a runtime env-var fallback that the *user* sets was deliberately rejected in #16. `install-hooks --project-strategy repo-root` instead **bakes** the strategy into the generated hook command (and the OpenCode / OMP / OpenClaw plugins) at install time — the same status as the already-baked `AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` / `--data-dir`, not a user runtime override. This is a client/install-time-only change: the server already parses `project_strategy=repo-root`. A marker's own `project_strategy` / `project` still win, and the default stays `basename` (baking nothing) so existing installs are byte-identical.+## 12. Operability- **Single binary**, statically-linked where possible. Distroless Docker image. **Absolute data path** by default (`dirs::data_local_dir().join("ai-memory")`); log it loudly on startup (agentmemory #303 lesson).diff --git a/docs/install.md b/docs/install.mdindex d4be146a..bc0e482e 100644--- a/docs/install.md+++ b/docs/install.md@@ -114,6 +114,25 @@ pointed at the same server instead of falling back to loopback.`init`, `serve`, and `generate-auth-token` do not need these env vars becausethey either create local files or start the server itself.+### Default project resolution (`--project-strategy`)++By default each session files memory under `basename(cwd)`. Because an agent+shell keeps its working directory between tool calls, a single+`mkdir sub && cd sub` reparents the rest of the session into a phantom project+named `sub`. To make every session for an install resolve its project from the+git repo root instead — collapsing subdirectories and worktrees — bake the+strategy into the hooks:++```bash+ai-memory install-hooks --apply --agent claude-code --project-strategy repo-root+```++`--project-strategy` accepts `basename` (the default; bakes nothing, so existing+installs are unchanged) or `repo-root`. It works for every agent and delivery+path. A per-repo `.ai-memory.toml` marker's own `project_strategy` / `project`+still take precedence — see+[the marker-file reference](marker-file.md#install-wide-default-no-marker).+---## Arch Linux native packages (AUR)diff --git a/docs/marker-file.md b/docs/marker-file.mdindex d9ab4b54..635b5608 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -150,15 +150,43 @@ ai-memory rename-project \--new-workspace movvia```+## Install-wide default (no marker)++`project_strategy = "repo-root"` normally lives in a marker, which means+dropping a `.ai-memory.toml` in (or above) every repo. To get the same+repo-root resolution for a whole install **without** a per-repo marker, bake+it into the generated hooks at install time:++```sh+ai-memory install-hooks --apply --agent claude-code --project-strategy repo-root+```++Every session for that install then resolves its project from the main git+repo root — so an agent that runs `mkdir sub && cd sub` and stays there no+longer forks the rest of the session into a phantom project named `sub`.++This is **install-time config**, written into the agent's hook command (and+the generated OpenCode / OMP / OpenClaw plugins) — the same status as the+`AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` it sits beside, *not* a user-set+runtime override (which was deliberately rejected in #16). The flag accepts+`basename` (the default — bakes nothing, behavior unchanged) or `repo-root`.++Precedence is unchanged: a marker's explicit `project_strategy` or `project`+still wins over the install default.+## What the marker file does NOT do- ❌ No glob patterns. Walk-up by literal ancestry only.- ❌ No merge of ancestor markers. Closest wins.- ❌ No automatic migration of `default`-workspace projects.- ❌ No automatic repo-root collapsing. Worktrees and subdirectories only- share a project when `project_strategy = "repo-root"` is explicitly set.-- ❌ No env / auth / hook-url override. Use the existing env vars- (`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`) for those.+ share a project when `project_strategy = "repo-root"` is explicitly set+ (per marker, or baked install-wide — see above).+- ❌ No user-set env / auth / hook-url override. Use the existing env vars+ (`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`) for those. (A repo-root+ *default* can still be baked into an install without a marker via+ `install-hooks --project-strategy repo-root`, but that is install-time+ config, not a runtime override the user sets in their shell.)## Troubleshooting