Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: add marker-file.md, link from README, CHANGELOG entry
Pablo Winter6ab96ce112db
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0bb37b42..e9c30ff9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- `.ai-memory.toml` marker file lets a directory tree declare its+ `workspace` (required) and `project` (optional) without depending on+ `basename($cwd)`. Lifecycle hook scripts walk up from `cwd` to find+ the closest marker and forward the declared names as+ `&workspace=X&project=Y` query params on `POST /hook` and+ `GET /handoff`. Server accepts the new params as optional overrides;+ absent marker means the previous behaviour (`workspace = "default"`,+ `project = basename(cwd)`) — fully backward compatible. See+ [`docs/marker-file.md`](docs/marker-file.md).- Oh My Pi / OMP is now a first-class integration: `install-mcp --client pi`and `--client omp` write native `~/.omp/agent/mcp.json` config, while`install-hooks --agent omp` and `--agent pi` write the TypeScript extensiondiff --git a/README.md b/README.mdindex 277898cc..28024126 100644--- a/README.md+++ b/README.md@@ -57,6 +57,10 @@ priors are at the [bottom](#influences-and-prior-art)."where you left off" block before its first prompt.- **Per-project isolation by construction.** Each project lives at`<wiki_root>/<workspace_id>/<project_id>/…` keyed by stable UUIDs.+ By default `workspace = "default"` and `project = basename($cwd)`.+ Drop a [`.ai-memory.toml` marker file](docs/marker-file.md) in any+ ancestor directory to override either — perfect for multi-client+ consultancies, work/personal split, or mono-repos.Same page path can exist in two projects without collision; arename is one column update; a purge is one `rm -rf`.- **Karpathy-style LLM wiki.** Pages are compiled from observationsdiff --git a/docs/marker-file.md b/docs/marker-file.mdnew file mode 100644index 00000000..6383b126--- /dev/null+++ b/docs/marker-file.md@@ -0,0 +1,133 @@+# Marker file: `.ai-memory.toml`++Declare which workspace (and optionally which project) an agent's+`cwd` belongs to, without depending on the directory's basename.++## Why++ai-memory namespaces every wiki page by `(workspace, project)`. By+default, `workspace = "default"` and `project = basename($cwd)`. That+works for a solo developer in `~/projects/<repo>` but breaks down+for the cases this marker file is built for:++- **Multi-client consultancies** with `~/projects/<client>/<repo>` —+ every client should land in a dedicated workspace, not "default".+- **Work / personal / open-source separation** for solo developers+ who want isolation by life context.+- **Mono-repos** where you'd like all packages under one project+ (instead of basename-of-each-package buckets) — or each package+ under its own project, your call.++The marker file lets you declare these mappings without forking+ai-memory or running CLI commands per directory.++## Where to put it++`.ai-memory.toml` in **any ancestor** of your `cwd`. Lifecycle hooks+walk up from `cwd` toward `$HOME` (or `/` if `$HOME` is unset) and+use the **first** marker found. Closer markers override outer ones.++## Schema++```toml+# Required.+workspace = "movvia"++# Optional. When present, forces project = "pe-portais" for every+# cwd inside this marker's tree. Omit it to let basename(cwd) drive+# the project name.+project = "pe-portais"+```++**Naming rules**, validated server-side:++- Lowercase ASCII, digits, dots, dashes, underscores+- Regex: `^[a-z0-9][a-z0-9._-]*$`++Anything else is rejected at `get_or_create_workspace` / `_project`+time, surfacing as a hook warning. The shell helper URL-encodes+defensively but the server's regex is the source of truth.++## Three canonical examples++### Multi-client++```+~/projects/movvia/.ai-memory.toml → workspace = "movvia"+~/projects/cliente-x/.ai-memory.toml → workspace = "cliente-x"+~/personal/.ai-memory.toml → workspace = "personal"+```++Outcome:++- `~/projects/movvia/pe-api-core` → workspace = `movvia`, project = `pe-api-core`+- `~/projects/cliente-x/api` → workspace = `cliente-x`, project = `api`+- `~/personal/blog` → workspace = `personal`, project = `blog`++### Mono-repo with grouped packages++```+~/projects/movvia/.ai-memory.toml → workspace = "movvia"+~/projects/movvia/pe-portais/.ai-memory.toml → workspace = "movvia"+ project = "pe-portais"+```++Outcome:++- `~/projects/movvia/pe/pe-api-core` → workspace = `movvia`, project = `pe-api-core`+- `~/projects/movvia/pe-portais/apps/web` → workspace = `movvia`, project = `pe-portais`+ (closer marker wins)++### Single workspace, no per-repo overrides++```+~/.ai-memory.toml → workspace = "home"+```++Every cwd under `$HOME` lands in workspace `home` with+`project = basename(cwd)`. Useful when you just want to opt out of+the `default` bucket entirely.++## Migrating existing projects++Projects already created under workspace `default` stay there. Move+one with the CLI:++```sh+ai-memory rename-project \+ --workspace default --project foo \+ --new-workspace movvia+```++## 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 env / auth / hook-url override. Use the existing env vars+ (`AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_HOOK_URL`) for those.++## Troubleshooting++**My marker isn't being picked up.** Walk through:++1. File is named exactly `.ai-memory.toml` (note the leading dot).+2. File is in an **ancestor** of the cwd — not a sibling, not a+ descendant.+3. There isn't a closer marker overriding it. Run+ `find ~/projects -maxdepth 5 -name '.ai-memory.toml'` to see all+ markers in your tree.+4. The workspace / project values match the regex above (lowercase+ alphanumerics, dots, dashes, underscores).++Hook scripts run fire-and-forget by design, so they don't log on+success. To see what's actually being sent, run a hook script by+hand:++```sh+printf '{"cwd":"%s"}' "$PWD" \+ | sh ~/.local/share/ai-memory/hooks/claude-code/post-tool-use.sh+```++If the marker is being read, the curl line (visible with `set -x`+or in server logs) will include `&workspace=...` in the URL.