Skip to content

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.md
index 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)`. Even
Project 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.md
index 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 because
they 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.md
index 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