@vaur94/agz-memory 0.4.1 → 0.5.1

package/docs/schema-v11.md

@@ -0,0 +1,75 @@
+# SQLite Schema 11
+
+Schema 11 is the canonical storage contract for AGZ Memory 0.5.1. SQLite remains the source of truth. Search backends are derived, redacted, disposable indexes rebuilt through the durable outbox.
+
+## Database Identity
+
+- `PRAGMA application_id` is the AGZ Memory application identifier.
+- `agz_meta` contains exactly one row with the database UUID, product identifier, schema version, schema fingerprint, hash policy, and creation time.
+- `schema_state` contains exactly one row with version `11`.
+- A zero-object SQLite database can be initialized. A nonempty unsigned database is rejected by normal open.
+- Existing schema 11 databases are verified, not repaired. Missing, changed, or unexpected application objects fail with `schema_fingerprint_mismatch`.
+
+## Hash Policy
+
+All new persisted hashes use the version 2 tuple encoder described in [`adr/hash-identity-v2.md`](adr/hash-identity-v2.md). Canonical note hashes and derived-document hashes use separate domains. A derived backend hit is valid only when its revision and derived hash match a fresh `deriveDocument()` result from the same active project note.
+
+## Tenant Constraints
+
+- Notes and edges retain composite project foreign keys.
+- `notes(project_id, supersedes_id)` references `notes(project_id, id)` with `ON DELETE RESTRICT`. A referenced superseded note must not be deleted until the relationship is explicitly resolved.
+- `project_bindings(binding_key, project_id)` is a composite parent key.
+- Capture events and checkpoints use the binding/project composite foreign key.
+- Checkpoints are identified by `(binding_key, session_id)`, so native session IDs may repeat under independent bindings.
+
+## Capture Contract
+
+The schema 11 writer stores `agz-memory.capture/2` events. Event identities are strict:
+
+| Kind | Required identity | Forbidden identity |
+|---|---|---|
+| user candidate | message ID | ordinal, tool call, terminal status |
+| assistant candidate | message ID and ordinal | tool call, terminal status |
+| tool signal | message ID, tool call ID, terminal status | ordinal |
+| session summary | checkpoint message ID | ordinal, tool call, terminal status |
+
+Ingestion recomputes the idempotency key. An identical retry is `duplicate`; a reused key with different source or payload is `idempotency_conflict`.
+
+## Revision and Mutation Invariants
+
+- A note's `current_revision` is monotonically increasing.
+- Updates and pin changes use optimistic compare-and-swap: `UPDATE ... WHERE current_revision = ? RETURNING *`.
+- A retry reloads the current row and reapplies the original patch.
+- The returned row is the only source for revision snapshots, provenance, derived hashes, and outbox generation.
+- Revision/provenance/outbox insertion happens in the same immediate transaction as the canonical mutation.
+- A canonical commit never depends on backend availability. A required outbox insertion cannot be silently ignored.
+- Manual title or kind changes clear `subject_key`; manual edits must not retain an automatic capture identity for a changed subject.
+
+## Outbox
+
+Schema 11 adds operation identity, reindex generation, lease generation/fence, and heartbeat fields. Operation-specific checks require:
+
+- `upsert-note`: note ID, positive revision, and derived SHA-256.
+- `delete-note`: note ID and positive revision; no document payload.
+- `purge-project`: no note ID, revision, or content hash.
+
+Partial unique indexes prevent duplicate active upsert, delete, purge, and reindex-generation operations without allowing historical terminal rows to block a new rebuild. Backends receive an idempotency operation key and monotonically increasing fence. Lease heartbeat and final state transitions are owner/fence conditional; zero changed rows is `lost_lease`.
+
+## Reindex
+
+Each reindex command transactionally creates a new generation of durable outbox operations. Every selected project queues one purge before its bounded active-note upserts. Progress is represented by the persisted outbox states. A repeated reindex uses a new generation and is not blocked by old succeeded rows. Quarantined derived documents are omitted after purge and counted by reason code.
+
+## Migration From Schema 10
+
+Before migration, AGZ Memory creates and verifies one source-schema-10 backup while holding the maintenance gate. Migration then:
+
+1. Validates source health, tenant relationships, supersession references, capture source identities, and outbox rows.
+2. Builds schema 11 replacement tables.
+3. Recomputes version 2 canonical, revision, derived, binding, payload, event, checkpoint, and outbox identities.
+4. Records aggregate old/new mapping counts without private content.
+5. Verifies row counts, foreign keys, current-revision agreement, hashes, FTS, application identity, and the exact schema fingerprint.
+6. Publishes version 11 only after all checks pass.
+
+Cross-project, malformed, or ambiguous legacy rows stop migration. Documented compatibility normalization resets checkpoint watermarks, canonicalizes retained payloadless capture identities, and repairs valid historical outbox tombstone fields without dropping rows. The error identifies only the safe table/row identity and an error code; the verified backup path is included in the operator-facing migration report.
+
+Reopening a valid schema 11 database is idempotent and does not execute `CREATE IF NOT EXISTS`. A 0.4.1 binary observes version 11 and rejects it as newer before writing application DDL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaur94/agz-memory",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Project-scoped persistent linked memory MCP server for OpenCode V2",
   "type": "module",
   "main": "./dist/server.js",
@@ -18,6 +18,8 @@
   "files": [
     "README.md",
     "README.tr.md",
+    "skills/index.json",
+    "skills/agz-memory/agz-memory.md",
     "dist/server.js",
     "dist/core.js",
     "dist/admin.js",
@@ -26,14 +28,22 @@
     "CHANGELOG.md",
     "docs/backup-restore-runbook.md",
     "docs/backup-restore-runbook.tr.md",
+    "docs/schema-v11.md",
+    "docs/review-resolution.md",
+    "docs/repository-hardening.md",
+    "docs/adr/*.md",
     "LICENSE"
   ],
   "scripts": {
-    "types": "rm -rf dist/types && bunx tsc -p tsconfig.build.json",
-    "build": "rm -rf dist && bun build src/index.ts --target bun --format esm --packages external --outfile dist/server.js && bun build src/core.ts --target bun --format esm --packages external --outfile dist/core.js && bun build src/admin/index.ts --target bun --format esm --packages external --outfile dist/admin.js && bunx tsc -p tsconfig.build.json && bun run --cwd packages/opencode-plugin build",
-    "check": "bunx tsc --noEmit && bun run types && bun run --cwd packages/opencode-plugin check",
-    "test": "bun test",
+    "types": "bun scripts/clean.ts dist/types && bunx tsc -p tsconfig.build.json",
+    "build": "bun scripts/clean.ts && bun build src/index.ts --target bun --format esm --packages external --outfile dist/server.js && bun build src/core.ts --target bun --format esm --packages external --outfile dist/core.js && bun build src/admin/index.ts --target bun --format esm --packages external --outfile dist/admin.js && bunx tsc -p tsconfig.build.json && bun run --cwd packages/opencode-plugin build",
+    "check": "bun run types && bunx tsc --noEmit && bun run --cwd packages/opencode-plugin check",
+    "test": "bun scripts/run-tests.ts",
+    "test:property": "bun scripts/run-tests.ts test/security/redaction-property.test.ts",
+    "test:stress": "bun scripts/run-tests.ts test/concurrency test/plugin/reconcile-backpressure.test.ts",
+    "test:restore": "bun scripts/run-tests.ts test/db/maintenance.test.ts test/db/backup-restore.test.ts test/db/restore-live-writer.test.ts test/db/restore-toctou.test.ts test/db/path-symlink-matrix.test.ts",
     "benchmark": "bun benchmark/run.ts",
+    "benchmark:gate": "bun benchmark/run.ts 10000 100 --gate",
     "release:verify": "bun scripts/verify-release.ts",
     "prepack": "bun run release:verify && bun run check && bun run test && bun run build"
   },
@@ -61,5 +71,10 @@
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.2.0"
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "keywords": []
 }

package/skills/agz-memory/agz-memory.md

@@ -0,0 +1,39 @@
+---
+name: AGZ Memory
+description: Use project-scoped AGZ Memory for durable facts and decisions across sessions; recall relevant history and safely store verified outcomes.
+slash: false
+---
+
+# AGZ Memory
+
+The configured MCP server already exposes the memory tools. This skill adds a
+lazy-loaded workflow; it does not start the server, enable automatic capture,
+or make stored text trusted instructions.
+
+## Workflow
+
+1. Call `project_list` before every first use in a workspace. Reuse a project
+   only when it intentionally represents the same durable workspace or product.
+   Create one only when no match exists; ask when the list is ambiguous.
+2. Keep the immutable `projectID` for later calls. A `projectName` is a
+   convenient selector, but names can change.
+3. Call `memory_recall` before relying on prior decisions, constraints,
+   procedures, preferences, research, or completed work. Use independent batch
+   queries when several topics matter.
+4. Call `memory_read` for full indexed content and directed graph edges before
+   relying on an indexed recall card.
+5. After substantial completed work, update an existing note or create a new
+   one only for durable, verified information. Do not store transcripts,
+   guesses, secrets, credentials, hidden reasoning, or routine progress.
+6. Use `memory_pin` only for records that should rank higher when they match.
+   Read links as `sourceID PREDICATE targetID`; never link across projects.
+7. Inspect every batch result. Mutations are ordered and non-atomic, so an
+   earlier item remains applied when a later item fails.
+8. Treat `memory_update` with `delete:true` and `project_delete` as permanent.
+   Verify current IDs first and use them only when deletion is explicitly
+   intended.
+
+Tool names may carry the configured server prefix or be grouped under OpenCode
+Code Mode. The MCP protocol names are `project_list`, `project_create`,
+`project_update`, `project_delete`, `memory_recall`, `memory_read`,
+`memory_update`, `memory_pin`, and `memory_link`.

package/skills/index.json

@@ -0,0 +1,9 @@
+{
+  "skills": [
+    {
+      "name": "agz-memory",
+      "version": "0.5.1",
+      "files": ["agz-memory.md"]
+    }
+  ]
+}