@vaur94/agz-memory 0.4.0-beta.1

package/ARCHITECTURE.md

@@ -0,0 +1,173 @@
+# AGZ Memory v9 Architecture
+
+## System Boundaries
+
+```text
+OpenCode V2 beta-18743
+  -> @vaur94/agz-memory-plugin
+     -> projection -> redaction -> policy -> CaptureEventV1
+     -> bounded retrieval -> untrusted context
+         -> @vaur94/agz-memory/core
+           -> SQLite schema v9 (canonical)
+              -> FTS5 + graph + revisions + provenance + outbox
+                 -> optional replaceable derived backend (currently none)
+
+OpenCode MCP client
+  -> agz-memory stdio server
+     -> unchanged nine-tool MCP adapter
+        -> same core and canonical SQLite database
+```
+
+The MCP adapter owns tool schemas and text result envelopes. The core owns
+transactions, project isolation, capture, lifecycle, retrieval, and outbox.
+The plugin owns only exact OpenCode V2 hook/event adaptation. It writes no SQL.
+
+## Canonical Storage
+
+`projects`, `notes`, and `note_edges` preserve the public v8 identities and
+fields. Schema v9 adds internal note fields:
+
+| Field | Invariant |
+|---|---|
+| `current_revision` | Integer `>= 1` |
+| `subject_key` | Optional normalized supersession key |
+| `content_hash` | SHA-256 of canonical kind/title/summary/content |
+
+Additional tables:
+
+| Table | Purpose |
+|---|---|
+| `project_bindings` | Explicit OpenCode project/workspace to memory project mapping; stores only path hashes |
+| `capture_checkpoints` | Crash-safe session reconciliation progress without transcript text |
+| `capture_events` | Bounded redacted idempotent event audit |
+| `note_provenance` | Source IDs, extractor/redaction versions, and confidence; no prompt/tool payload |
+| `note_revisions` | Full snapshot for every committed note state |
+| `index_outbox` | Payload-free at-least-once derived-index queue |
+
+`schema_state` is the only schema version source and contains exactly `9` after
+migration. Foreign keys are enabled during normal operation.
+
+## Transaction Invariants
+
+- Create commits note, provenance, revision, FTS trigger, and outbox together.
+- Patch and pin increment revision only when values actually change.
+- Hard note delete cascades revision, provenance, edge, and FTS state.
+- Project delete queues payload-free backend purge operations before project
+  cascades, in the same transaction.
+- Supersession marks the old note `superseded`, snapshots it, creates the active
+  replacement, adds a `SUPERSEDES` edge, and writes outbox operations atomically.
+- Capture materialization commits the event disposition and note lifecycle in
+  one transaction.
+
+The partial unique index on `(project_id, kind, subject_key)` applies only to
+active notes with a subject key. Manual MCP notes keep `subject_key = NULL`, so
+the existing free-form contract remains unchanged.
+
+## FTS And Retrieval
+
+`notes_fts` is an external-content FTS5 table keyed by `notes.rowid`. Insert,
+update, and delete triggers maintain it inside note transactions. Migration
+uses FTS `rebuild` and compares note/FTS counts.
+
+Retrieval channels are bounded:
+
+| Channel | Candidate limit |
+|---|---:|
+| Lexical BM25 | 40 |
+| Optional semantic | 40 |
+| One-hop graph | 30 |
+
+Weighted reciprocal rank fusion uses `1.00`, `0.80`, and `0.35` channel weights
+with constant `60`. Every semantic hit is re-read by `(project_id, note_id)` and
+rejected when missing, inactive, cross-project, stale-revision, or hash-mismatched.
+Semantic failure falls back to lexical retrieval.
+
+The injection formatter emits only kind, opaque ID, title, and summary. It
+escapes delimiter characters, includes a fixed untrusted-data warning, limits
+output to eight cards and 4,800 characters, and never injects full note content.
+
+## Capture Pipeline
+
+The plugin uses the exact `@opencode-ai/plugin@0.0.0-beta-18743` Promise API:
+
+- `ctx.session.hook("prompt")`
+- `ctx.session.hook("context")`
+- `ctx.tool.hook("execute.after")`
+- `ctx.event.subscribe({ signal })`
+- `ctx.session.get({ sessionID })`
+- `ctx.session.context({ sessionID })`
+
+The live event stream is a latency hint, not the canonical ingestion boundary.
+Prompt checkpoints and bounded context reconciliation recover missed terminal
+events. Event reconnect uses bounded backoff. Plugin cleanup aborts the stream,
+disposes hooks, and waits only a bounded period.
+
+The projection boundary accepts user prompt text and assistant terminal text.
+It excludes reasoning, tool arguments/results, attachments, files, shell output,
+system/synthetic/skill/compaction parts, paths, diffs, environment values, and
+provider state. Tool capture stores only name, terminal status, opaque native
+IDs, and a normalized error type.
+
+Redaction runs before extraction and again inside core. High-risk payloads are
+quarantined with `payload_json = NULL`. Raw secret values and hashes are not
+stored in capture audit tables.
+
+## Binding And Isolation
+
+Plugin bindings require memory project UUID, OpenCode project ID, optional
+workspace ID, and a verified canonical directory. Raw paths are not persisted.
+The binding key is:
+
+```text
+sha256("opencode-v2\0" + projectID + "\0" + workspaceID + "\0" + sha256(realpath))
+```
+
+Basenames are never project identities. Event location or session location must
+match the active plugin instance. Missing, conflicting, moved, or cross-project
+bindings disable capture/injection for that callback.
+
+## Backup And Migration
+
+Migration uses `<database>.migration.lock/owner.json`, mode `0700/0600`, with
+PID, process-start marker, host, timestamp, target schema, and random owner ID.
+A live owner cannot be broken by runtime or admin.
+
+Before v8-to-v9 DDL:
+
+1. Checkpoint WAL and validate source integrity/foreign keys.
+2. Create a unique `VACUUM INTO` snapshot.
+3. Validate the snapshot on a separate connection.
+4. Write SHA-256, byte size, schema, SQLite version, and row counts to a manifest.
+5. Fsync temporary files and the backup directory, then atomically rename.
+6. Rebuild notes/edges, create revision/provenance rows, create v9 tables and
+   trigger-based FTS, and set schema `9` as the final SQL step.
+7. Re-enable and verify foreign keys, integrity, counts, revisions, and FTS.
+
+Failure closes the candidate DB and restores the verified snapshot. Restore
+never overwrites the previous canonical DB; it preserves the old file and
+quarantines WAL/SHM sidecars.
+
+## Outbox
+
+Outbox work is FIFO per `(backend, project_id)`. Atomic claims use random worker
+lease IDs and expiry. Stale revision upserts complete without export. Vendor
+exports apply redaction again and derive a hash from the redacted document.
+High-risk manual notes remain canonical but are not exported.
+
+Delivery is at least once and adapters must be idempotent by opaque project/note
+key. Ten failed attempts move work to `dead`; canonical note commits are never
+rolled back by a derived backend outage.
+
+## Fail-Open And Fail-Closed
+
+| Operation | Behavior |
+|---|---|
+| Plugin capture/injection | Fail-open; OpenCode request continues |
+| Semantic query | Lexical fallback |
+| Binding conflict | Fail-closed for memory feature |
+| Secret quarantine | Fail-closed for note write |
+| MCP mutation | Transaction rollback and explicit tool error |
+| Migration/restore | Fail-closed; service does not start on partial state |
+
+Logs contain allowlisted operation/outcome/error codes only. Prompt, query,
+note text, paths, tool payloads, headers, and credentials are never logged.

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.4.0-beta.1 - 2026-08-31
+
+- Added verified backup manifests, migration locking, schema v9, restore, and
+  the `agz-memory-admin` binary.
+- Added note revisions, provenance, trigger-maintained FTS5, supersession, and
+  payload-free derived-index outbox processing.
+- Added strict `CaptureEventV1`, deterministic idempotency, double redaction,
+  quarantine, retention, and explicit high-confidence auto-write policy.
+- Added bounded lexical/graph/hybrid retrieval contracts and untrusted context
+  formatting.
+- Added the separate exact-beta OpenCode V2 plugin package with safe `off`
+  default and staged rollout modes.
+- Preserved all nine MCP tool names, selectors, result envelopes, project
+  isolation, and destructive confirmations.
+- Renamed the public repository, packages, binaries, MCP server, and plugin to
+  AGZ Memory while retaining legacy persisted contract identifiers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGZ Memory contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# AGZ Memory
+
+English | [Türkçe](README.tr.md)
+
+Project-scoped persistent memory for OpenCode V2. The repository publishes two
+lockstep packages:
+
+- `@vaur94/agz-memory`: the nine-tool stdio MCP server, reusable core, and
+  recovery-oriented admin CLI.
+- `@vaur94/agz-memory-plugin`: optional safe capture and bounded context
+  injection for an exact OpenCode V2 beta.
+
+SQLite schema v9 is the canonical source of truth. Optional semantic services
+are disposable derived indexes and are disabled unless their isolation,
+deletion, purge, and quality contracts pass the benchmark gates.
+
+## Compatibility
+
+| Component | Version |
+|---|---|
+| Core/MCP | `0.4.0-beta.1` |
+| Plugin | `0.4.0-beta.1` |
+| OpenCode V2 | `0.0.0-beta-18743` |
+| `@opencode-ai/plugin` | `0.0.0-beta-18743` |
+| Bun | `>=1.3.14` |
+| SQLite schema | `9` |
+
+The plugin disables itself when the running OpenCode version does not exactly
+match its supported beta. The MCP server remains independently usable.
+
+## MCP Server
+
+```sh
+bunx @vaur94/agz-memory@0.4.0-beta.1
+```
+
+OpenCode V2 configuration uses `mcp.servers`:
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "agz-memory": {
+        "type": "local",
+        "command": ["bunx", "@vaur94/agz-memory@0.4.0-beta.1"],
+        "environment": {
+          "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
+        },
+        "codemode": false
+      }
+    }
+  }
+}
+```
+
+The default database path is
+`~/.local/share/opencode-memory/memory.sqlite`. Override it with
+`OPENCODE_MEMORY_DATABASE_PATH` before starting OpenCode.
+
+### Tools
+
+The external MCP contract remains exactly nine tools:
+
+| Tool | Purpose |
+|---|---|
+| `project_list` | List immutable project IDs and current names |
+| `project_create` | Create an empty project |
+| `project_update` | Rename a project without changing its ID |
+| `project_delete` | Permanently delete one confirmed project |
+| `memory_recall` | Project-filtered FTS5 and one-hop graph recall |
+| `memory_update` | Create, patch, or permanently delete notes |
+| `memory_pin` | Set note priority inside one project |
+| `memory_link` | Add same-project graph edges |
+| `memory_read` | Read full note bodies and graph edges |
+
+Every `memory_*` request selects exactly one `projectID` or `projectName`.
+Cross-project reads, updates, deletes, links, and recall are rejected. Ordered
+batches are intentionally non-atomic, so inspect every item result.
+
+Project deletion requires all three values:
+
+```json
+{
+  "projectID": "<immutable UUID>",
+  "confirmProjectName": "<exact current case-sensitive name>",
+  "confirmation": "DELETE_PROJECT_AND_ALL_MEMORY"
+}
+```
+
+## Optional OpenCode Plugin
+
+The plugin is a separate package so the moving OpenCode beta dependency never
+enters the MCP-only runtime. Its safe default is `off`.
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@vaur94/agz-memory-plugin@0.4.0-beta.1",
+      "options": {
+        "mode": "off",
+        "autoCreateProjects": false,
+        "bindings": [],
+        "capture": {
+          "enabled": false,
+          "allowedKinds": ["preference", "decision"],
+          "minConfidence": 0.95
+        },
+        "retrieval": {
+          "semanticBackend": "none",
+          "timeoutMs": 300,
+          "maxCards": 8,
+          "maxCharacters": 4800
+        }
+      }
+    }
+  ]
+}
+```
+
+Bindings are explicit allowlist entries. The plugin never selects a memory
+project by basename and never auto-creates one:
+
+```jsonc
+{
+  "memoryProjectID": "<UUID from project_list>",
+  "opencodeProjectID": "<ctx.location.project.id>",
+  "canonicalDirectory": "/absolute/canonical/project/path",
+  "workspaceID": "<optional workspace ID>"
+}
+```
+
+The rollout modes are cumulative:
+
+| Mode | Capture | Retrieval | Injection | Auto-write |
+|---|---:|---:|---:|---:|
+| `off` | No | No | No | No |
+| `shadow-capture` | Redacted audit only | No | No | No |
+| `shadow-retrieval` | Yes | Metrics only | No | No |
+| `inject` | Yes | Yes | Bounded | No |
+| `auto-write` | Yes | Yes | Bounded | Explicit high-confidence decisions/preferences only |
+
+Injection is fail-open, summary-only, limited to eight cards and 4,800
+characters, and wrapped as `trust="untrusted"`. A memory timeout or binding
+error does not block the main OpenCode request.
+
+## Capture Safety
+
+The canonical event contract remains `opencode2-memory.capture/1` for database
+and event compatibility with earlier releases.
+
+- Native session/message/ordinal/tool IDs produce deterministic SHA-256
+  idempotency keys. SQLite uniqueness is the final duplicate guard.
+- Projection discards reasoning, tool input/output, attachments, files, system
+  parts, diffs, environment data, and provider state.
+- Text is redacted before extraction and again inside the core before any DB
+  insert.
+- Private keys, credential URIs, multiple high-risk secrets, and canaries are
+  quarantined without a text payload.
+- Event JSON is limited to 16 KiB; automatic content is limited to 4,800
+  characters.
+- `[memory:off]` disables capture for that user message.
+- Auto-write initially accepts only explicit `preference` and `decision`
+  candidates at confidence `>= 0.95`.
+
+## Schema V9
+
+Schema v9 preserves project, note, edge, timestamp, status, and pin identities
+while adding:
+
+- `project_bindings`
+- `capture_checkpoints`
+- `capture_events`
+- `note_provenance`
+- `note_revisions`
+- `index_outbox`
+
+Every committed note state has provenance and a full revision snapshot. Note
+create, patch, pin, supersession, FTS triggers, and derived-index outbox writes
+share transactions. Normal recall only returns `active` notes.
+
+FTS5 now uses external content and insert/update/delete triggers rather than
+manual synchronization.
+
+## Backup, Upgrade, And Restore
+
+The admin binary writes JSON to stdout and sanitized errors to stderr:
+
+```sh
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin upgrade --to 9
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin capture status
+```
+
+Every schema upgrade takes an atomic migration lock and creates a verified
+`VACUUM INTO` snapshot plus a SHA-256 manifest before DDL runs. Integrity,
+foreign keys, table counts, revision invariants, and FTS counts are checked.
+
+Restore is dry-run unless the manifest hash and confirmation are supplied:
+
+```sh
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin restore \
+  /path/to/memory.sqlite.backup/<manifest>.manifest.json
+
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin restore \
+  /path/to/memory.sqlite.backup/<manifest>.manifest.json \
+  --sha256 <manifest-database-sha256> \
+  --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
+```
+
+Stop every MCP/plugin writer before an upgrade or restore. The current database
+is preserved as `failed-restore-source-*`; WAL/SHM sidecars are quarantined.
+See [`docs/backup-restore-runbook.md`](docs/backup-restore-runbook.md).
+
+## Semantic Backend Decision
+
+Production remains `semanticBackend: "none"`. The exact vendor contract review
+did not produce a complete live A/B proof for all required server-side project
+filter, deterministic delete, purge, leakage, and latency gates. SQLite
+lexical+graph retrieval is therefore the production path. See
+[`benchmark/baselines/vendor-decision.json`](benchmark/baselines/vendor-decision.json).
+
+## Development
+
+```sh
+bun install
+bun test
+bun run check
+bun run build
+npm pack --dry-run --json
+```
+
+The test suite includes MCP snapshots, legacy and v8-to-v9 migration fixtures,
+backup/restore, revisions, outbox FIFO, capture idempotency, secret quarantine,
+retrieval isolation, bounded formatter, and exact-beta plugin hook smoke tests.

package/README.tr.md

@@ -0,0 +1,240 @@
+# AGZ Memory
+
+[English](README.md) | Türkçe
+
+OpenCode V2 için proje kapsamlı kalıcı hafıza. Depo, sürümleri birlikte ilerleyen
+iki paket yayımlar:
+
+- `@vaur94/agz-memory`: dokuz araçlı stdio MCP sunucusu, yeniden kullanılabilir
+  çekirdek ve kurtarma odaklı yönetim komut satırı aracı.
+- `@vaur94/agz-memory-plugin`: exact bir OpenCode V2 beta sürümü için isteğe
+  bağlı güvenli yakalama ve sınırlı bağlam ekleme eklentisi.
+
+SQLite schema v9, tek yetkili veri kaynağıdır. İsteğe bağlı anlamsal servisler
+yeniden üretilebilir türetilmiş indekslerdir; izolasyon, silme, temizleme ve
+kalite sözleşmeleri benchmark kapılarından geçmedikçe kapalı kalır.
+
+## Uyumluluk
+
+| Bileşen | Sürüm |
+|---|---|
+| Core/MCP | `0.4.0-beta.1` |
+| Plugin | `0.4.0-beta.1` |
+| OpenCode V2 | `0.0.0-beta-18743` |
+| `@opencode-ai/plugin` | `0.0.0-beta-18743` |
+| Bun | `>=1.3.14` |
+| SQLite schema | `9` |
+
+Eklenti, çalışan OpenCode sürümü desteklenen beta ile tam eşleşmediğinde
+kendisini devre dışı bırakır. MCP sunucusu bağımsız olarak kullanılabilir.
+
+## MCP Sunucusu
+
+```sh
+bunx @vaur94/agz-memory@0.4.0-beta.1
+```
+
+OpenCode V2 yapılandırması `mcp.servers` alanını kullanır:
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "agz-memory": {
+        "type": "local",
+        "command": ["bunx", "@vaur94/agz-memory@0.4.0-beta.1"],
+        "environment": {
+          "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
+        },
+        "codemode": false
+      }
+    }
+  }
+}
+```
+
+Varsayılan veritabanı yolu `~/.local/share/opencode-memory/memory.sqlite` olur.
+OpenCode başlamadan önce `OPENCODE_MEMORY_DATABASE_PATH` ile değiştirilebilir.
+
+### Araçlar
+
+Dış MCP sözleşmesi tam olarak dokuz araçtan oluşur:
+
+| Araç | Amaç |
+|---|---|
+| `project_list` | Değişmez proje kimliklerini ve güncel adları listeler |
+| `project_create` | Boş bir proje oluşturur |
+| `project_update` | Kimliği değiştirmeden projeyi yeniden adlandırır |
+| `project_delete` | Onaylanmış tek bir projeyi kalıcı olarak siler |
+| `memory_recall` | Proje filtreli FTS5 ve tek adımlı grafik araması yapar |
+| `memory_update` | Not oluşturur, günceller veya kalıcı olarak siler |
+| `memory_pin` | Proje içindeki not önceliğini ayarlar |
+| `memory_link` | Aynı proje içinde grafik bağlantısı ekler |
+| `memory_read` | Tam not içeriklerini ve grafik bağlantılarını okur |
+
+Her `memory_*` isteği tam olarak bir `projectID` veya `projectName` seçer.
+Projeler arası okuma, güncelleme, silme, bağlantı ve arama reddedilir. Sıralı
+toplu işlemler kasıtlı olarak atomik değildir; her öğenin sonucu incelenmelidir.
+
+Proje silmek için üç değerin de sağlanması gerekir:
+
+```json
+{
+  "projectID": "<immutable UUID>",
+  "confirmProjectName": "<exact current case-sensitive name>",
+  "confirmation": "DELETE_PROJECT_AND_ALL_MEMORY"
+}
+```
+
+## İsteğe Bağlı OpenCode Eklentisi
+
+Hareketli OpenCode beta bağımlılığının yalnız MCP kullanan çalışma ortamına
+girmemesi için eklenti ayrı bir pakettir. Güvenli varsayılanı `off` değeridir.
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "@vaur94/agz-memory-plugin@0.4.0-beta.1",
+      "options": {
+        "mode": "off",
+        "autoCreateProjects": false,
+        "bindings": [],
+        "capture": {
+          "enabled": false,
+          "allowedKinds": ["preference", "decision"],
+          "minConfidence": 0.95
+        },
+        "retrieval": {
+          "semanticBackend": "none",
+          "timeoutMs": 300,
+          "maxCards": 8,
+          "maxCharacters": 4800
+        }
+      }
+    }
+  ]
+}
+```
+
+Bağlamalar açık izin listesi girdileridir. Eklenti bir hafıza projesini hiçbir
+zaman klasör adına göre seçmez ve otomatik proje oluşturmaz:
+
+```jsonc
+{
+  "memoryProjectID": "<UUID from project_list>",
+  "opencodeProjectID": "<ctx.location.project.id>",
+  "canonicalDirectory": "/absolute/canonical/project/path",
+  "workspaceID": "<optional workspace ID>"
+}
+```
+
+Rollout modları birikimli olarak ilerler:
+
+| Mod | Yakalama | Getirme | Ekleme | Otomatik yazma |
+|---|---:|---:|---:|---:|
+| `off` | Hayır | Hayır | Hayır | Hayır |
+| `shadow-capture` | Yalnız maskelenmiş denetim | Hayır | Hayır | Hayır |
+| `shadow-retrieval` | Evet | Yalnız ölçüm | Hayır | Hayır |
+| `inject` | Evet | Evet | Sınırlı | Hayır |
+| `auto-write` | Evet | Evet | Sınırlı | Yalnız açık ve yüksek güvenli karar/tercihler |
+
+Bağlam ekleme fail-open çalışır; yani hafıza hatası ana isteği engellemez. Yalnız
+özetleri kullanır, sekiz kart ve 4.800 karakterle sınırlıdır ve
+`trust="untrusted"` olarak sarılır. Hafıza zaman aşımı veya bağlama hatası ana
+OpenCode isteğini durdurmaz.
+
+## Yakalama Güvenliği
+
+Veritabanı ve önceki sürümlerin olay uyumluluğu için yetkili olay sözleşmesi
+`opencode2-memory.capture/1` olarak korunur.
+
+- Yerel session/message/ordinal/tool kimlikleri belirlenebilir SHA-256 tekilleştirme
+  anahtarları üretir. SQLite benzersizliği son tekrar korumasıdır.
+- Projeksiyon; reasoning, araç girdisi/çıktısı, ekler, dosyalar, sistem parçaları,
+  diff, ortam verileri ve sağlayıcı durumunu atar.
+- Metin, çıkarımdan önce ve veritabanına yazılmadan önce çekirdek içinde tekrar
+  maskelenir.
+- Özel anahtarlar, kimlik bilgisi URI'ları, birden çok yüksek riskli sır ve
+  canary değerleri metin yükü olmadan karantinaya alınır.
+- Olay JSON'u 16 KiB, otomatik içerik 4.800 karakter ile sınırlıdır.
+- `[memory:off]`, ilgili kullanıcı mesajı için yakalamayı kapatır.
+- Otomatik yazma başlangıçta yalnız güveni `>= 0.95` olan açık `preference` ve
+  `decision` adaylarını kabul eder.
+
+## Schema V9
+
+Schema v9; proje, not, bağlantı, zaman damgası, durum ve pin kimliklerini korur.
+Eklenen tablolar:
+
+- `project_bindings`
+- `capture_checkpoints`
+- `capture_events`
+- `note_provenance`
+- `note_revisions`
+- `index_outbox`
+
+Kaydedilen her not durumunda kaynak bilgisi ve tam revision görüntüsü bulunur.
+Not oluşturma, güncelleme, pin, supersession, FTS trigger ve türetilmiş indeks
+outbox yazımları aynı transaction içinde yapılır. Normal arama yalnız `active`
+notları döndürür.
+
+FTS5 artık elle eşitleme yerine dış içerik ile insert/update/delete trigger'larını
+kullanır.
+
+## Yedekleme, Yükseltme Ve Geri Yükleme
+
+Yönetim binary'si JSON çıktısını stdout'a, temizlenmiş hataları stderr'e yazar:
+
+```sh
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin upgrade --to 9
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin capture status
+```
+
+Her schema yükseltmesi atomik bir migration lock alır ve DDL çalışmadan önce
+SHA-256 manifest içeren doğrulanmış bir `VACUUM INTO` snapshot oluşturur.
+Bütünlük, foreign key, tablo sayıları, revision kuralları ve FTS sayıları kontrol
+edilir.
+
+Manifest hash'i ve onay sağlanmadıkça geri yükleme yalnız kuru çalışır:
+
+```sh
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin restore \
+  /path/to/memory.sqlite.backup/<manifest>.manifest.json
+
+bunx --package @vaur94/agz-memory@0.4.0-beta.1 agz-memory-admin restore \
+  /path/to/memory.sqlite.backup/<manifest>.manifest.json \
+  --sha256 <manifest-database-sha256> \
+  --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
+```
+
+Yükseltme veya geri yükleme öncesinde tüm MCP/plugin yazıcılarını durdurun. Güncel
+veritabanı `failed-restore-source-*` olarak korunur; WAL/SHM yan dosyaları
+karantinaya alınır. Ayrıntılar için
+[`docs/backup-restore-runbook.md`](docs/backup-restore-runbook.md) belgesine bakın.
+
+## Anlamsal Backend Kararı
+
+Üretim `semanticBackend: "none"` olarak kalır. Tam vendor sözleşmesi incelemesi,
+zorunlu sunucu tarafı proje filtresi, belirlenebilir silme, purge, sızıntı ve
+gecikme kapılarının tümü için eksiksiz canlı A/B kanıtı üretmedi. Bu nedenle
+üretim yolu SQLite metin+grafik aramasıdır. Ayrıntılar:
+[`benchmark/baselines/vendor-decision.json`](benchmark/baselines/vendor-decision.json).
+
+## Geliştirme
+
+```sh
+bun install
+bun test
+bun run check
+bun run build
+npm pack --dry-run --json
+```
+
+Test paketi; MCP snapshot'ları, eski sürüm ve v8-to-v9 migration fixture'ları,
+yedekleme/geri yükleme, revision'lar, outbox FIFO, capture tekilleştirme, sır
+karantinası, retrieval izolasyonu, sınırlı formatter ve exact-beta plugin hook
+smoke testlerini içerir.