Skip to content

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.md
index 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 extension
diff --git a/README.md b/README.md
index 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; a
rename is one column update; a purge is one `rm -rf`.
- **Karpathy-style LLM wiki.** Pages are compiled from observations
diff --git a/docs/marker-file.md b/docs/marker-file.md
new file mode 100644
index 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.