@vaur94/agz-memory 0.5.0 → 0.5.2

package/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # AGZ Memory Architecture
 
-This document describes the `0.5.0` runtime and SQLite schema v11.
+This document describes the `0.5.2` runtime and SQLite schema v11.
 
 ## System Boundaries
 
@@ -20,7 +20,7 @@ OpenCode V2 beta-18743
 
 SQLite outbox
   -> optional derived retrieval backend
-      -> disabled in 0.5.0; backend = none
+      -> disabled in 0.5.2; backend = none
 ```
 
 The MCP adapter owns tool schemas, annotations, and result envelopes. The core
@@ -98,7 +98,10 @@ Capture requires all of these gates:
 
 1. The plugin version and running OpenCode beta match exactly.
 2. Mode is not `off`, capture is enabled, and exactly one explicit binding
-   matches project ID, workspace ID, and canonical directory.
+   matches project ID, workspace ID, and canonical directory. A linked Git
+   worktree may match its main checkout only after reciprocal worktree metadata
+   proves that both use the same common Git directory; persisted binding paths
+   are not rewritten.
 3. Only terminal user/assistant text or terminal tool status is projected.
 4. Credential and private-key patterns are removed or quarantined.
 5. The strict `CaptureEventV2` parser enforces UTF-8 size, kind-specific source identity, event
@@ -133,7 +136,7 @@ original OpenCode context unchanged.
 
 Semantic providers implement an optional backend contract: project-filtered
 query, idempotent upsert, deterministic delete, full project purge, and health.
-No provider is enabled in `0.5.0`. The SQLite lexical/graph path remains fully
+No provider is enabled in `0.5.2`. The SQLite lexical/graph path remains fully
 functional without one.
 
 ## Derived Index Outbox

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 All notable changes to AGZ Memory are recorded here. The project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.5.2] - 2026-09-04
+
+### Changed
+
+- Updated linked Git worktree guidance so a main checkout and its linked
+  worktrees safely reuse the same `memoryProjectID` after Git metadata confirms
+  the shared common directory.
+- Preserved persisted binding path and key compatibility while allowing distinct
+  OpenCode project/workspace identities to map to that shared memory project.
+- Aligned release metadata, package examples, and bilingual operational guidance
+  with the 0.5.2 release surface.
+
+### Compatibility
+
+- Retained SQLite schema 11, the exact nine-tool MCP contract, and inert plugin
+  defaults across the worktree identity guidance change.
+
+## [0.5.1] - 2026-09-04
+
+### Changed
+
+- Hardened Phase 1 stabilization with the migration-root fix, shared limits and
+  typed errors, bounded pagination, strict default-off plugin configuration,
+  bounded late attachment/shutdown, and resumable administrative reindexing.
+- Added the 10-sample p95 migration timing artifact, safe clean/evidence
+  tooling, and keyed quarantine HMAC rotation with Windows fail-closed behavior.
+
+### Security
+
+- Preserved exactly nine MCP tools, SQLite schema 11, semantic backend `none`,
+  and inert plugin defaults.
+
 ## [0.5.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -10,6 +10,9 @@ as two independently usable packages that advance at the same version:
 - `@vaur94/agz-memory-plugin`: an optional OpenCode V2 adapter for bounded
   retrieval and deliberately staged automatic capture.
 
+**0.5.2 status:** This repository documents the 0.5.2 release surface and
+compatibility contract; npm publication and Git hosting state are tracked separately.
+
 The MCP server is ready for normal use. The plugin starts inert: no project is
 created, no session is captured, and no context is injected until an explicit
 binding and rollout mode are configured.
@@ -32,8 +35,8 @@ binding and rollout mode are configured.
 
 | Component | Supported version |
 |---|---|
-| Core and MCP | `0.5.0` |
-| OpenCode plugin | `0.5.0` |
+| Core and MCP | `0.5.2` |
+| OpenCode plugin | `0.5.2` |
 | OpenCode V2 | `0.0.0-beta-18743` |
 | `@opencode-ai/plugin` | `0.0.0-beta-18743` |
 | Bun | `>=1.3.14` |
@@ -47,7 +50,7 @@ itself unless the running OpenCode version exactly matches the supported beta.
 Run the server directly:
 
 ```sh
-bunx @vaur94/agz-memory@0.5.0
+bunx @vaur94/agz-memory@0.5.2
 ```
 
 Or register it in OpenCode V2 under `mcp.servers`:
@@ -55,13 +58,13 @@ Or register it in OpenCode V2 under `mcp.servers`:
 ```jsonc
 {
   "skills": [
-    "https://raw.githubusercontent.com/ugur-murat-alt/agz-memory/v0.5.0/skills/"
+    "https://raw.githubusercontent.com/ugur-murat-alt/agz-memory/v0.5.2/skills/"
   ],
   "mcp": {
     "servers": {
       "agz-memory": {
         "type": "local",
-        "command": ["bunx", "@vaur94/agz-memory@0.5.0"],
+        "command": ["bunx", "@vaur94/agz-memory@0.5.2"],
         "environment": {
           "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
         },
@@ -111,7 +114,8 @@ OpenCode exposes the tools with the configured server prefix, for example
 Recommended sequence:
 
 1. Call `project_list` and reuse an existing project when it represents the
-   same durable workspace.
+   same durable workspace. Git linked worktrees are separate checkouts of that
+   workspace and must reuse its `projectID`.
 2. Call `project_create` only when no matching project exists.
 3. Keep the returned `projectID`; names can change, UUIDs cannot.
 4. Call `memory_recall` before relying on historical decisions.
@@ -130,7 +134,7 @@ options:
 {
   "plugins": [
     {
-      "package": "@vaur94/agz-memory-plugin@0.5.0",
+      "package": "@vaur94/agz-memory-plugin@0.5.2",
       "options": {
         "mode": "off",
         "autoCreateProjects": false,
@@ -171,9 +175,13 @@ an OpenCode project/workspace/location to an existing AGZ Memory project:
 ```
 
 `memoryProjectID` must come from `project_list`. The directory is resolved with
-the filesystem and compared with the active OpenCode location. Only a hash of
-that canonical path is persisted. A mismatched location or duplicate mapping
-disables the plugin rather than selecting a project heuristically.
+the filesystem and compared with the active OpenCode location. A main checkout
+and a linked Git worktree are accepted as the same repository only when their
+Git metadata confirms the shared common directory. Configure each distinct
+OpenCode project/workspace identity explicitly, but reuse the same
+`memoryProjectID`; the configured canonical path and its persisted hash remain
+unchanged. An unrelated or unverifiable location and a duplicate mapping disable
+the plugin rather than selecting a project heuristically.
 
 ## Roll Out Safely
 
@@ -203,11 +211,11 @@ quality, and latency gates.
 The admin CLI reads the same `OPENCODE_MEMORY_DATABASE_PATH`:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin upgrade --to 11
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin upgrade --to 11
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin outbox status
 ```
 
 Upgrades take an exclusive migration lock and create a verified backup before
@@ -216,7 +224,7 @@ restore. Restore and backup deletion use dry-run output plus explicit
 confirmation values; never guess them.
 
 Use [the backup and restore runbook](docs/backup-restore-runbook.md) for a full
-rehearsal. Final `0.5.0` backup manifests use `agz-memory-backup/1`; prerelease
+rehearsal. The `0.5.2` backup manifests use `agz-memory-backup/1`; prerelease
 manifests must be handled by the prerelease that created them.
 
 ## Security Model

package/README.tr.md

@@ -10,6 +10,9 @@ Aynı sürümde ilerleyen, birbirinden bağımsız kullanılabilen iki paket sun
 - `@vaur94/agz-memory-plugin`: sınırlı geri çağırma ve bilinçli olarak aşamalı
   otomatik yakalama için isteğe bağlı OpenCode V2 bağdaştırıcısı.
 
+**0.5.2 durumu:** Bu depo 0.5.2 sürüm yüzeyini ve uyumluluk sözleşmesini
+belgeler; npm yayımlama ve Git barındırma durumu ayrı olarak izlenir.
+
 MCP sunucusu normal kullanım için hazırdır. Eklenti hareketsiz başlar: açık bir
 eşleme ve devreye alma modu verilene kadar proje oluşturmaz, oturum yakalamaz ve
 bağlam eklemez.
@@ -32,8 +35,8 @@ bağlam eklemez.
 
 | Bileşen | Desteklenen sürüm |
 |---|---|
-| Çekirdek ve MCP | `0.5.0` |
-| OpenCode eklentisi | `0.5.0` |
+| Çekirdek ve MCP | `0.5.2` |
+| OpenCode eklentisi | `0.5.2` |
 | OpenCode V2 | `0.0.0-beta-18743` |
 | `@opencode-ai/plugin` | `0.0.0-beta-18743` |
 | Bun | `>=1.3.14` |
@@ -47,7 +50,7 @@ MCP sunucusu bir OpenCode beta sürümüne bağlı değildir. İsteğe bağlı e
 Sunucuyu doğrudan çalıştırın:
 
 ```sh
-bunx @vaur94/agz-memory@0.5.0
+bunx @vaur94/agz-memory@0.5.2
 ```
 
 Ya da OpenCode V2 içinde `mcp.servers` altına kaydedin:
@@ -55,13 +58,13 @@ Ya da OpenCode V2 içinde `mcp.servers` altına kaydedin:
 ```jsonc
 {
   "skills": [
-    "https://raw.githubusercontent.com/ugur-murat-alt/agz-memory/v0.5.0/skills/"
+    "https://raw.githubusercontent.com/ugur-murat-alt/agz-memory/v0.5.2/skills/"
   ],
   "mcp": {
     "servers": {
       "agz-memory": {
         "type": "local",
-        "command": ["bunx", "@vaur94/agz-memory@0.5.0"],
+        "command": ["bunx", "@vaur94/agz-memory@0.5.2"],
         "environment": {
           "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
         },
@@ -112,7 +115,8 @@ OpenCode araçları yapılandırılan sunucu önekiyle gösterir; örneğin
 Önerilen sıra:
 
 1. `project_list` çağırın ve aynı kalıcı çalışma alanını temsil eden mevcut
-   projeyi yeniden kullanın.
+   projeyi yeniden kullanın. Git bağlantılı çalışma ağaçları bu çalışma alanının
+   ayrı kod kopyalarıdır ve aynı `projectID` değerini kullanmalıdır.
 2. Yalnız eşleşen proje yoksa `project_create` çağırın.
 3. Dönen `projectID` değerini saklayın; ad değişebilir, UUID değişmez.
 4. Geçmiş kararlara dayanmadan önce `memory_recall` çağırın.
@@ -132,7 +136,7 @@ ayarlarla ekleyin:
 {
   "plugins": [
     {
-      "package": "@vaur94/agz-memory-plugin@0.5.0",
+      "package": "@vaur94/agz-memory-plugin@0.5.2",
       "options": {
         "mode": "off",
         "autoCreateProjects": false,
@@ -173,9 +177,13 @@ OpenCode proje/çalışma alanı/konumunu mevcut AGZ Memory projesine bağlar:
 ```
 
 `memoryProjectID`, `project_list` sonucundan gelmelidir. Dizin gerçek dosya
-sistemi yoluna çözülür ve etkin OpenCode konumuyla karşılaştırılır. Yalnız bu
-kanonik yolun özeti veritabanına yazılır. Yanlış konum veya çift eşleme,
-sezgisel proje seçmek yerine eklentiyi kapatır.
+sistemi yoluna çözülür ve etkin OpenCode konumuyla karşılaştırılır. Ana kod
+kopyası ile bağlantılı Git çalışma ağacı, yalnız Git metadata'sı ortak dizini
+doğruladığında aynı depo kabul edilir. Her farklı OpenCode proje/çalışma alanı
+kimliğini açıkça eşleyin, fakat aynı `memoryProjectID` değerini yeniden kullanın;
+yapılandırılmış kanonik yol ve veritabanındaki özeti değişmez. İlişkisiz veya
+doğrulanamayan konum ya da çift eşleme, sezgisel proje seçmek yerine eklentiyi
+kapatır.
 
 ## Güvenli Devreye Alma
 
@@ -205,11 +213,11 @@ kapılarından geçene kadar `semanticBackend` değeri `none` olmalıdır.
 Yönetim aracı aynı `OPENCODE_MEMORY_DATABASE_PATH` değerini okur:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin upgrade --to 11
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.5.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin upgrade --to 11
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.5.2 agz-memory-admin outbox status
 ```
 
 Yükseltmeler özel bir geçiş kilidi alır ve veritabanını değiştirmeden önce
@@ -218,7 +226,7 @@ dener. Geri yükleme ve yedek silme işlemleri önce deneme çıktısı, sonra a
 onay değerleri ister; bu değerleri tahmin etmeyin.
 
 Tam prova için [yedekleme ve geri yükleme runbook'unu](docs/backup-restore-runbook.tr.md)
-kullanın. Final `0.5.0` yedek manifestleri `agz-memory-backup/1` kullanır;
+kullanın. `0.5.2` yedek manifestleri `agz-memory-backup/1` kullanır;
 ön sürüm manifestleri onları oluşturan ön sürümle işlenmelidir.
 
 ## Güvenlik Modeli