Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: changelog, marker file and boundary inventory for repository identity (#708)
luisfnicolaud9f8e2f5ec4e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 11150555..c45d418a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0down for the bulk delete and restored from its own `sqlite_master` DDLafterwards, so the cleanup does not re-tokenize tens of gigabytes of ledgerbody one row at a time. (#914)+- `identity = "…"` in `.ai-memory.toml` pins the repository identity a+ checkout's captures route by, outranking `project` and the git remote — see+ [marker-file.md](docs/marker-file.md#repository-identity). (#708)- The builtin web UI has a root-only `/web/pending` page to triage pendingauto-improvement proposals. It lists the proposals of all projects, with aproject filter and a sort, and shows the rationale and the proposed body.@@ -248,6 +251,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0(`collateral_observations_deleted`, `collateral_handoffs_denulled`). TheCLI still exits non-zero without `--confirm`; against an older server, orif the preview times out, it prints only the existing refusal. (#945)+- Captures from a checkout with no declared `project` and a git remote now route+ by the repository's identity — the normalised `upstream` remote, else `origin`+ — instead of the folder name (`projects.identity`, V70). Two unrelated+ repositories sharing a folder name now get two projects (the second named+ after its owner, e.g. `orgb-api`); one repository cloned into differently+ named folders converges on one project, the first to claim the identity —+ an existing second project keeps its history but stops receiving captures.+ Existing projects are claimed in place, so upgrading moves no memory, and a+ user who may not write to a project cannot claim its identity. Checkouts+ that declare `project` in their marker route by name exactly as before. Every+ hook client (native, shell, PowerShell, TypeScript) resolves the identity+ host-side and sends it as `identity` / `identity_src`; credentials in a remote+ URL never leave the machine. (#708)- A capture into a project its author may not write is dropped server-sideand counted as `dropped_unauthorized` in status, never stored. The nativehook client treats a 403 from the server as final and drops the eventdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 2b5f51e9..bd331e68 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -285,7 +285,7 @@ separately gated Claude Code assistant/Stop excerpt remains capped at 2 KB.| Table | What ||---|---|-| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. `projects.access_mode` (V68; `open` default / `restricted`) decides whether any authenticated user or only root, the creator (`projects.created_by`, V69) and grant holders (`project_grants`, V68) reach it, decided by `ai_memory_store::authorize_project` — `docs/users.md#per-project-access`. |+| `workspaces`, `projects` | Top of the 3-tuple identity coordinate. `projects.identity` / `identity_source` (V70, #708) hold the repository identity a project routes by — an explicit marker `identity` or a normalised git remote, resolved client-side — unique per workspace when set; empty until a capture claims the project. See `docs/marker-file.md#repository-identity`. `projects.access_mode` (V68; `open` default / `restricted`) decides whether any authenticated user or only root, the creator (`projects.created_by`, V69) and grant holders (`project_grants`, V68) reach it, decided by `ai_memory_store::authorize_project` — `docs/users.md#per-project-access`. || `pages` | Versioned wiki pages with `is_latest` + `supersedes` chain. M8 columns: `last_accessed_at`, `access_count`, and decay-only tombstone marker `superseded_at`. M9 cols: `embedding_provider`, `embedding_model`, `embedding_dim`. V36: `expires_at` (frontmatter TTL). V37: `salience` (NULL = `salience_default`; derived from `page_feedback`). || `pages_fts` | FTS5 virtual table over `(title, body)`, auto-synced by triggers. || `sessions`, `observations` | Sanitized, bounded lifecycle-hook projections. `sessions.ended_observation_count` is the stable generation watermark for resumed-session re-end eligibility; wall clocks are not used for that decision. They are an operational audit trail, not a complete native transcript. |diff --git a/docs/marker-file.md b/docs/marker-file.mdindex 331c5cd4..0417aa03 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -57,7 +57,9 @@ hook capture and handoff lookup send the same `cwd`, `workspace`, `project`,`project_strategy`, `drop_subagent`, `default_global`, `briefing`, and`briefing_budget` query params to the server when a marker declares them;handoff lookup also sends `cwd` when no marker exists so the default-`project = basename(cwd)` route works consistently.+`project = basename(cwd)` route works consistently. Every client also sends+`identity` / `identity_src` when the checkout has a repository identity (see+[Repository identity](#repository-identity)), with or without a marker.## Schema@@ -76,6 +78,15 @@ project = "pe-portais"# `project` is present.project_strategy = "repo-root"+# Optional. Pin this checkout's repository identity: the key its captures+# route by, whatever the folder is called and wherever it is checked out.+# Outranks `project` and the git remote. Use it for a directory with no+# remote that must not collide with every other folder of the same name,+# for two checkouts that should share one memory, or for a monorepo+# subdirectory that deserves its own. Case-folded. See "Repository+# identity" below.+identity = "acme/platform"+# Optional. Opt this project into drop_subagent_captures: set it to "true"# and the server accepts but does NOT store this project's subagent-session# captures. A multi-agent harness fans one goal out to many subagent@@ -360,6 +371,42 @@ when the server runs in a container that cannot see the host checkout.Put the marker anywhere on the walk-up path from the worktree — commonlya single `~/.ai-memory.toml` — to select the strategy.+### Repository identity++A project's name comes from its folder, and folder names collide: two+unrelated repositories both checked out as `api/` would otherwise share one+project. On a server with per-project grants (#708) that means one grant, so+every client resolves a **repository identity** for the checkout and sends it+with each event. The first rung that yields one wins:++1. `identity = "…"` in the marker;+2. `project = "…"` in the marker;+3. the `upstream` git remote, else `origin`, normalised+ (`[email protected]:Acme/API.git` → `github.com/acme/api`);+4. the folder name.++Only rungs 1 and 3 change routing. A declared `project` routes by name as it+always has — a statement outranks the remote, so a fork whose marker names+its own project is never filed under the repository it forked from — and a+bare folder name routes exactly as before. What routes by identity is an+undeclared checkout with a remote, or a checkout with an explicit+`identity`:++- The project already carrying the identity wins, whatever it is called:+ `~/work/api` and `~/dev/acme-api`, both cloned from `github.com/acme/api`,+ are one project.+- An existing project with that name and no identity yet is **claimed in+ place** by the first capture that may write to it, so upgrading moves no+ memory.+- If the name already belongs to a different identity, the new repository+ gets its own project, named from its owner (`github.com/orgb/api` →+ `orgb-api`, then `orgb-api-2`, …).++The remote is normalised on the host, so credentials embedded in a remote+URL never leave the machine. Other remote names (`fork`, `mine`) are+ignored on purpose: they differ per person, and would give one repository a+different identity for each of them.+### Single workspace, no per-repo overrides```diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex c873e2c1..5fe7c271 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -50,6 +50,7 @@ boundary not yet built.| 12 | Network/auth posture | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer` | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401 | STRONG || 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), never falls back to a link it set aside, and turns an `AmbiguousNativeSession` into a warning with nothing imported; `ai-memory-workstream/src/transcript.rs` `discover_crush` claims only the one top-level session created (or, with `--continue`, touched) during the run, and in a data directory outside the project only one that edited a file in it | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run`; `run.rs` `ambiguous_crush_discovery_keeps_the_run`; `transcript.rs` `crush_discovery_claims_only_the_session_the_run_created`, `crush_discovery_in_a_shared_store_claims_only_an_edit_here` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout; Crush, which has no hooks, relies on that discovery alone and claims nothing when it is ambiguous || 14 | Per-project authorization (#708) | `ai-memory-store/src/project_authz.rs` `authorize_project` / `ProjectAuthz::authorize` choke point (V68 `project_grants` + `projects.access_mode`, default `open`; V69 `projects.created_by` feeds `is_creator`); `scope.rs` `ScopeResolver::with_project_authz` (reader pool for reads, writer actor for writes) and its free forms `authorize_scope_for` / `*_guarded`, attached for every DB user by `ai-memory-mcp` `scope_resolver_as`, `ai-memory-web` `authorize_read` / `lookup_project`, and `ai-memory-hooks` (`grants.rs` `authorize_resolved` for run/workstream ids, the capture check in `router.rs`); read-shaped mutations resolve at `ProjectAccess::Write` (`resolve_existing_args(.., need)`); unscoped reads filtered before `LIMIT` by `reader.rs` `readable_repository_sql`; `WriterHandle::authorize_project` as defense in depth. Page ids are never taken from a caller (only derived from already-authorized hits), so there is no page-id entry point to guard | `tests/suite/project_authz.rs` (decision matrix, ship-inert, resolver gate); `tests/suite/access_mode.rs` `every_caller_against_both_modes`, `a_restricted_project_admits_the_team_and_refuses_the_outsider`, `new_projects_follow_the_server_default_and_admit_their_creator`; `scope.rs` `the_argument_shape_does_not_decide_the_level`, `a_user_reaches_only_what_they_were_granted`, `creating_authorizes_against_a_project_that_already_exists`, `a_refused_scope_fails_the_search_instead_of_shortening_it`; `grants.rs` `search_finds_only_what_the_viewer_may_read`, `the_limit_counts_only_what_the_viewer_may_see`, `the_workspace_handoff_comes_only_from_readable_repositories`; `ai-memory-mcp` `server.rs` `a_reader_may_read_everything_and_change_nothing`, `bob_cannot_read_alices_page_in_a_restricted_project`, `bob_cannot_find_alices_page_by_searching_in_a_restricted_project`, `bob_cannot_consolidate_a_session_in_alices_repository`, `a_restricted_projects_queues_need_write`; `ai-memory-hooks` `a_capture_needs_writer_on_the_repository_it_lands_in`, `session_start_delivers_nothing_from_a_repository_the_viewer_cannot_read`, `run_and_workstream_ids_only_answer_someone_who_may_reach_the_repository`; `ai-memory-web` `web_reads_honour_grants_in_a_restricted_project`, `metadata_shows_only_what_the_viewer_may_read` — each with a granted or open-project control, and proven to fail with the choke point (18 tests) or the SQL filter (9 tests) neutralized | STRONG — slice 3 closed both bypass classes (unscoped reads, raw-id entry points) and added the root-only management surface. Out of scope by design: per-project administrators (granting/restricting is root-only), and access modes, creators and grants live only in SQLite, so `reindex` resets them |+| 14b | Repository identity routing (#708) | `ai-memory-store/src/ops.rs` `resolve_project_by_identity` — one transaction; an identity already on a project is never overwritten; an unclaimed project is claimed only when the capturing user may write it (the choke point's `resolve_project_authz` on the same transaction), otherwise it is returned unclaimed; a different identity under the same name splits into a new project with no shared `repo_path`; `ai-memory-hooks/src/router.rs` `cache_key_for` keys the path cache by identity too; `ai-memory-core/src/repository_identity.rs` strips credentials from remote URLs client-side, and the server accepts only the routing rungs (`explicit`, `git_remote`) from the wire | `tests/suite/identity_resolution.rs` `an_outsider_cannot_take_an_unclaimed_projects_identity` (control: `an_existing_project_is_claimed_in_place`), `two_unrelated_repositories_with_one_folder_name_stay_apart`, `a_created_or_split_project_admits_its_creator`; `router.rs` `one_path_with_two_remotes_is_two_projects`, `two_api_checkouts_with_different_remotes_get_two_projects` (a manifest rung on the wire is ignored); `repository_identity.rs` credential and normalisation tables — the claim guard and the cache key each proven to fail their test when removed | STRONG — first claimant wins: in a restricted workspace a user who creates a project under a remote identity first holds it until root grants others |## Keeping this current (the standing protocol)