@astragenie/astramemory-local 0.7.2

package/README.md

@@ -0,0 +1,419 @@
+# AstraMemory Local
+
+Local-first memory daemon for AI coding agents — wire-compatible with `memory-plugin` (v0.2.0+).
+
+> **v0.2.0 closes the schema gap**  
+> Daemon v0.2.0 now accepts the SaaS-canonical wire envelope: `{event, turns[], wire_version (required), scrub metadata, client_version, captured_at, project_id, cwd}` alongside backward-compatible `{session_id, source, content}`. The daemon and SaaS backend now share a wire contract. See the [astramemory-plugin FEAT 4a spec](https://github.com/astragenie/astramemory-plugin/blob/main/docs/superpowers/specs/2026-06-29-hooks-provider-migration-4a.md) for the unified wire contract and migration timeline.
+
+## Wire compatibility
+
+The daemon's ingest endpoint now speaks the same wire protocol as the SaaS backend. Both old and new clients work:
+
+**Legacy plugin (v0.1.x):**
+```json
+POST /ingest/transcript
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "session_id": "claude-20260630-abc123",
+  "source": "precompact",
+  "content": "[Assistant]: Distilled 3 facts..."
+}
+```
+
+**SaaS canonical (v0.2.0+):**
+```json
+POST /ingest/transcript
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "event": "pre_compact",
+  "session_id": "claude-20260630-abc123",
+  "turns": [{"role": "user", "content": "..."}, ...],
+  "wire_version": "v1.0",
+  "captured_at": "2026-06-30T12:34:56Z",
+  "client_version": "0.5.0",
+  "project_id": "my-project",
+  "cwd": "/home/user/src"
+}
+```
+
+Both shapes are accepted — no migration needed. See [src/contracts/wire.ts](src/contracts/wire.ts) for the complete schema definition.
+
+## Why it exists
+
+Claude Code sessions compact and terminate, taking context with them. AstraMemory Local captures
+every session transcript, distills typed memories (decisions, facts, lessons, commands, todos),
+and serves them back via hybrid search (BM25 + vector + importance + freshness). It runs entirely
+on your workstation — no cloud account, no data leaves your machine. The plugin's hooks post to
+the local daemon instead of the SaaS endpoint through a single environment variable swap.
+
+---
+
+## Quick start (5 commands)
+
+```bash
+bun add -g @astragenie/astramemory-local
+astra-memory init
+# follow the wizard — picks Ollama or Azure, writes config.yaml + secrets.env
+astra-memory service install
+export MEMORY_API_URL=http://127.0.0.1:7777
+export MEMORY_BEARER=$(astra-memory token print)
+```
+
+Restart Claude Code. All plugin hooks (PreCompact, SessionEnd, SubagentStop) now post to the
+local daemon. No other plugin changes needed.
+
+---
+
+## Architecture
+
+```
+ memory-plugin hooks
+    |
+    |  POST /ingest/transcript (v0.2.0+ — SaaS-canonical envelope)
+    |  Authorization: Bearer <token>
+    v
++------------------+      SQLite (memory.sqlite)
+|  HTTP daemon     | ---> +-------------------+
+|  Fastify         |      | sessions          |
+|  127.0.0.1:7777  |      | messages          |
+|  (v0.2.0+)       |      | transcripts       |
++------------------+      | ingest_idempotency|
+                          | jobs (queue)      |
+                          | memories          |
+                          | memories_fts (FTS5)|
+                          | memories_vec (vec0)|
+                          | budget_spend      |
+                          +-------------------+
+                                   |
+                          in-process worker loop
+                                   |
+                          8-stage distillation
+                          (cleanup -> normalize ->
+                           chunk -> compact ->
+                           extract -> reduce ->
+                           memory-normalize ->
+                           embed + index)
+                                   |
+                    +--------------+--------------+
+                    |              |              |
+              memories        FTS5 index    sqlite-vec
+                (rows)       (BM25 search)  (cosine ANN)
+                    |              |              |
+                    +--------------+--------------+
+                                   |
+                          hybrid score fusion
+                          a*BM25 + b*cosine +
+                          c*importance + d*freshness
+                                   |
+                          GET /search  POST /recall
+                                   |
+                          /recall in plugin slash commands
+```
+
+Single Node process. Workers run in-process on a polling loop. SQLite is the source of truth.
+Everything derived (vectors, FTS rows, compactions) can be rebuilt by replaying the jobs table.
+
+---
+
+## Memory types
+
+| Type       | Description                                            | Example                                      |
+|------------|--------------------------------------------------------|----------------------------------------------|
+| `decision` | Architectural or design choice made during a session   | "Use sqlite-vec for v1 vector storage"       |
+| `fact`     | Objective project fact, configuration detail           | "Port 7777 is the default daemon port"       |
+| `lesson`   | Something that went wrong and how it was resolved      | "sqlite-vec rowid must match memories rowid" |
+| `command`  | CLI command or script worth remembering                | "bun run build && bun run test -- migrate"   |
+| `todo`     | Outstanding work item surfaced in conversation         | "Add reembed job when provider changes"      |
+
+---
+
+## Provider matrix
+
+| Concern         | Ollama (local, free)                     | Azure OpenAI (cloud)                         |
+|-----------------|------------------------------------------|----------------------------------------------|
+| LLM compaction  | qwen2.5-coder:7b (default)              | gpt-4.1 or any deployment                   |
+| LLM extraction  | qwen2.5-coder:7b (default)              | gpt-4.1 or any deployment                   |
+| Embedding       | nomic-embed-text-v2-moe (1024-dim)      | text-embedding-3-small (1024 via dimensions) |
+| Cost            | $0 (local inference)                     | ~$0.02/1K tokens + $0.0001/1K embed tokens  |
+| Setup           | `ollama serve` + `ollama pull <model>`   | Azure portal + endpoint + deployment name    |
+
+Providers are configurable independently per stage. Embedding provider is system-wide — switching
+requires `astra-memory rebuild --reembed` to re-index all memories in the new model's vector space.
+
+See [docs/providers.md](docs/providers.md) for full setup instructions.
+
+---
+
+## Public endpoints
+
+All endpoints require Bearer token authentication except `GET /version` and `GET /health`.
+`GET /dashboard` additionally accepts an `HttpOnly` session cookie, bootstrapped via a one-time
+`?token=` visit (see [Dashboard](#dashboard) below).
+
+| Endpoint | Auth | Description |
+|---|---|---|
+| `GET /health` | — | Daemon health probe: `{ ok, version, wire_versions_supported, schema_version }` |
+| `GET /version` | — | Version discovery: `{ name, version, wire_versions_supported, schema_version, ts }` |
+| `POST /ingest/transcript` | Bearer | Capture protocol endpoint — accepts `transcript` and `events` kinds; idempotency via `Idempotency-Key` header. See [docs/capture-protocol.md](docs/capture-protocol.md). |
+| `GET /search` | Bearer | Hybrid search with type/repo/project/since filters |
+| `POST /recall` | Bearer | Top-K semantic recall (alias: `search` with k=5) |
+| `POST /recall/pack` | Bearer | Token-budgeted memory pack for a repo/project/branch — powers the SessionStart hook |
+| `POST /remember` | Bearer | Direct memory insert, bypasses distillation |
+| `GET /memory/:id` | Bearer | Single memory lookup |
+| `GET /memory/:id/why` | Bearer | Provenance receipt — extraction evidence + confidence for a memory |
+| `GET /memory/:id/history` | Bearer | Full `memory_events` log for a memory (invalidate/supersede/promote chain) |
+| `POST /memory/:id/invalidate` | Bearer | Soft-delete a memory (lifecycle op) |
+| `POST /memory/:id/supersede` | Bearer | Replace a memory with a newer one, linked via `memory_events` |
+| `POST /memory/:id/promote` | Bearer | Promote a memory's scope: personal → team → org |
+| `POST /memory/:id/used` | Bearer | Record an explicit recall-usefulness signal for a memory |
+| `GET /sessions/:id/digest` | Bearer | Session summary digest |
+| `GET /dashboard` | Bearer, cookie, or one-time `?token=` bootstrap | Read-only HTML metrics dashboard, auto-refreshing every 5s |
+| `POST /mcp` | Bearer | Model Context Protocol endpoint (auto-discovered tools, see below) |
+
+## MCP tools (Claude Code auto-discovery)
+
+The daemon exposes a **Model Context Protocol** (Streamable HTTP) endpoint at `POST /mcp`.
+Claude Code discovers and calls the tools below automatically when configured in `.mcp.json`.
+
+| Tool | Description | Maps to |
+|---|---|---|
+| `search_memory` | Hybrid FTS + vector search with optional type/repo/project/since filters | `GET /search` |
+| `recall_memory` | Top-K semantic recall (default k=5) | `POST /recall` |
+| `remember` | Direct memory insert, bypasses distillation | `POST /remember` |
+| `get_health` | Daemon health probe: `{ ok, version, wire_versions_supported, schema_version }` | `GET /health` |
+| `why_memory` | Provenance receipt — extraction evidence + confidence for a memory | `GET /memory/:id/why` |
+| `session_digest` | Session summary digest | `GET /sessions/:id/digest` |
+| `invalidate_memory` | Soft-delete a memory (lifecycle op) | `POST /memory/:id/invalidate` |
+| `supersede_memory` | Replace an old memory with a new one, linked via `memory_events` | `POST /memory/:id/supersede` |
+| `promote_memory` | Promote a memory's scope: personal → team → org | `POST /memory/:id/promote` |
+| `memory_history` | Full `memory_events` log for a memory | `GET /memory/:id/history` |
+| `mark_memory_used` | Explicit recall-usefulness signal — "this memory mattered" | `POST /memory/:id/used` |
+
+**Plugin `.mcp.json` wiring:**
+
+```json
+{
+  "mcpServers": {
+    "astramem": {
+      "type": "http",
+      "url": "${MEMORY_API_URL}/mcp",
+      "headers": { "Authorization": "Bearer ${MEMORY_BEARER}" }
+    }
+  }
+}
+```
+
+Set `MEMORY_API_URL=http://127.0.0.1:7777` and `MEMORY_BEARER` to your token
+(printed by `astra-memory token print`).
+
+---
+
+## Budget cap
+
+The daily LLM spend cap (default: **$10 USD**) is enforced before each LLM call.
+
+- Ollama always reports `$0` cost — the cap only applies to Azure usage.
+- When the cap is reached, pending distillation jobs move to `paused` state. Ingest continues
+  to accept transcripts (no data loss). Distillation resumes the next UTC day automatically.
+- Override: `astra-memory budget --reset` (logged).
+- Check current spend: `astra-memory budget`.
+
+---
+
+## Security
+
+### Encryption at rest
+
+`memory.sqlite` is encrypted by default using `better-sqlite3-multiple-ciphers` (SQLCipher-compatible
+cipher driver). The 32-byte key is resolved through a provider chain:
+
+1. **OS credential store** — Windows Credential Manager / macOS Keychain / Linux libsecret, via
+   `@napi-rs/keyring`.
+2. **Key-file fallback** — `<configDir>/db.key` (mode `0600`) with a WARN log, used only when the
+   credential store throws (e.g. headless Linux with no secret-service session).
+
+A pre-existing plaintext `memory.sqlite` (from a version predating encryption) is **auto-migrated**
+transparently on daemon startup: the file is checkpointed, re-keyed via `PRAGMA rekey`, and
+verified (row-count match) before the encrypted copy replaces the original. The pre-migration
+plaintext file is preserved at `memory.sqlite.pre-encryption.bak` — nothing is deleted. Migration
+is idempotent; an already-encrypted file is a no-op.
+
+Disabling encryption (`security.encryption.enabled: false`) is a deliberate trust trade-off — the
+daemon logs a prominent WARN at startup, and `astra-memory doctor` reports
+`encryption: OFF — memory.sqlite is stored in PLAINTEXT`.
+
+### Stage-0 secret redaction
+
+Every transcript turn and manual `/remember` write passes through a redaction choke point *before*
+it is persisted — downstream pipeline stages only ever see already-redacted text. Detection runs in
+three passes:
+
+1. **PEM private-key blocks** (multiline, whole block).
+2. **Vendor/pattern detectors** — AWS access keys, GitHub tokens, Azure storage keys/SAS tokens, GCP
+   API keys, Slack tokens, JWTs, generic `key=value` credentials, connection-string userinfo — plus
+   any org-specific regexes from `security.redaction.customPatterns`.
+3. **Shannon-entropy fallback** — flags high-entropy strings (default threshold 4.0 bits/char) that
+   pattern detectors missed.
+
+Matches are replaced with a placeholder — `[REDACTED:<type>:<hash8>]`, where `hash8` is the first 8
+hex chars of `SHA-256(secret value)` — so the same secret always redacts to the same placeholder
+(dedup-safe) while the raw value is **never stored or logged**. Only counts are persisted, in the
+`redaction_log` table (`type`, `count`, `session_id`, `created_at`) — `astra-memory doctor` surfaces
+a 7-day breakdown, e.g. `redaction: on — 12 secrets redacted (3 aws_access_key, 9 generic_credential) in last 7d`.
+Toggle with `security.redaction.enabled` (default `true`).
+
+### Bearer token storage
+
+The daemon's Bearer token is stored the same way as the DB encryption key: OS credential store
+first, `secrets.env` (mode `0600`) only as a fallback when the credential store is unavailable. A
+token found only in `secrets.env` is opportunistically promoted into the credential store the next
+time the daemon resolves it — `secrets.env` itself is never rewritten or deleted as part of that
+promotion.
+
+---
+
+## Capture protocol
+
+`astramem-local` accepts session capture from any tool that can speak one small HTTP contract —
+`POST /ingest/transcript` with an `astramem-capture@1` envelope. Two kinds are supported:
+
+- **`transcript`** (default) — raw turns, run through the full 8-stage distillation pipeline.
+- **`events`** — pre-typed atom candidates (decision/fact/lesson/command/todo/note/event) that skip
+  the raw-text/LLM stages and enter directly at the reduce stage. Built for sources that already
+  know their own semantics (e.g. `runner-plugin` slice grades and lessons).
+
+Both kinds pass through the same stage-0 redaction choke point described above. Writing a new tool
+integration is a small translator — capture at the tool surface, shape into one envelope per session
+boundary, POST it. See [docs/capture-protocol.md](docs/capture-protocol.md) for the full contract,
+field reference, and a curl example.
+
+---
+
+## Memory lifecycle
+
+Every memory has an append-only history in the `memory_events` log. Lifecycle operations never
+delete a row — they append an event and update derived state:
+
+| Operation | Effect |
+|---|---|
+| **Invalidate** | Soft-deletes a memory (optionally with a reason) — it stops surfacing in search/recall. |
+| **Supersede** | Replaces an old memory with a new one; the two are linked via the event log. |
+| **Promote** | Widens a memory's scope: `personal` → `team` → `org` (downward/same-scope transitions are rejected). |
+
+`GET /memory/:id/history` (and the `memory_history` MCP tool) return the full event chain for a
+memory — the complete invalidate/supersede/promote provenance trail.
+
+**`why_memory` receipts** (`GET /memory/:id/why`, MCP `why_memory`) answer "why does the daemon
+believe this?" — they return the extraction evidence and confidence that produced the memory, so a
+recalled fact or decision can be traced back to its source.
+
+---
+
+## Usefulness metric
+
+The daemon tracks a **recall-usefulness rate**: of the memories served by a search/recall/pack call,
+how many were later marked as actually used (`POST /memory/:id/used`, MCP `mark_memory_used`, or the
+REST twin). The rate is `distinct atoms used / distinct atoms served` in a given time window,
+computed per memory type and per surface (`mcp` / `rest` / `cli`).
+
+This is a **v1 measure-only signal** — it does not yet feed ranking (see ADR-010). Query text is
+never stored; only a truncated SHA-256 digest of the query is kept alongside the served/used events,
+themselves appended to the same `memory_events` log lifecycle operations use.
+
+---
+
+## Dashboard
+
+`GET /dashboard` serves a single-file, auto-refreshing (every 5s) HTML metrics page — no
+JavaScript, no CDN, no external assets, dark mode by default. It shows memory counts by type,
+recent captures, job-queue state, distill throughput, provider health, today/MTD budget spend vs
+cap, and the pending-capture queue depth.
+
+Auth accepts either the usual `Authorization: Bearer <token>` header, or an `HttpOnly` session
+cookie. To open the dashboard directly in a browser (which can't set an `Authorization` header),
+visit it once with `?token=<bearer>` — the daemon exchanges that for the cookie via a 302 redirect
+to the clean URL, so the bearer never persists in browser history or gets re-sent by the
+`<meta refresh>` poll. A missing or wrong credential returns a plain-text 401, never HTML, and the
+query string is stripped from the log line so a wrong `?token=` guess doesn't persist a candidate
+secret.
+
+---
+
+## Commands reference
+
+| Command                                    | What it does                                       |
+|--------------------------------------------|----------------------------------------------------|
+| `astra-memory init [--no-hook]`            | Interactive wizard — writes config + secrets, runs migrations, installs service, offers the SessionStart memory-pack hook |
+| `astra-memory serve [--port N]`            | Start daemon in foreground (dev/debug)             |
+| `astra-memory service install`             | Register daemon as a user-scope OS service         |
+| `astra-memory service status`              | Show service state                                 |
+| `astra-memory service start`               | Start the service                                  |
+| `astra-memory service stop`                | Stop the service                                   |
+| `astra-memory service uninstall`           | Remove the service unit                            |
+| `astra-memory doctor`                      | Run all health checks, print table                 |
+| `astra-memory doctor --json`               | Machine-readable health check output               |
+| `astra-memory search "<query>"`            | Hybrid search, print results table                 |
+| `astra-memory search "<query>" --type decision` | Filter by memory type                       |
+| `astra-memory recall "<question>"`         | Top-5 semantic recall (alias for search k=5)       |
+| `astra-memory remember "<text>" [--type]`  | Direct insert, bypasses distillation pipeline      |
+| `astra-memory queue`                       | Show pending/failed jobs                           |
+| `astra-memory queue --state failed`        | Show only failed jobs                              |
+| `astra-memory rebuild [--reembed]`         | Rebuild derived indexes; --reembed re-vectors all  |
+| `astra-memory providers list`              | List configured providers and their health         |
+| `astra-memory providers test [name]`       | Ping provider, print latency + dim                 |
+| `astra-memory budget`                      | Show today and month spend vs cap                  |
+| `astra-memory budget --reset`              | Clear today's spend counter (override, logged)     |
+| `astra-memory token print`                 | Print the current Bearer token                     |
+| `astra-memory token rotate`                | Generate new token, invalidate the old one         |
+
+---
+
+## Further reading
+
+- [docs/migration-from-saas.md](docs/migration-from-saas.md) — switch the plugin from remote SaaS to local daemon
+- [docs/configuration.md](docs/configuration.md) — full config.yaml reference
+- [docs/providers.md](docs/providers.md) — Ollama and Azure OpenAI setup
+- [docs/capture-protocol.md](docs/capture-protocol.md) — `astramem-capture@1` wire contract (`transcript` + `events` kinds)
+- [docs/hooks/memory-pack.md](docs/hooks/memory-pack.md) — SessionStart memory-pack hook (auto-installed by `init`)
+- [docs/troubleshooting.md](docs/troubleshooting.md) — common issues and fixes
+- [docs/contracts.md](docs/contracts.md) — frozen type interfaces (for contributors)
+- [CHANGELOG.md](CHANGELOG.md) — release history
+
+---
+
+## Development
+
+This project uses [Bun](https://bun.sh/) as the package manager and script runner.
+
+```bash
+bun install          # install dependencies
+bun run build        # compile TypeScript → dist/
+bun run test         # run the vitest suite
+```
+
+**Publishing** (maintainers only):
+
+```bash
+bun publish          # publishes to GitHub Packages via .npmrc (same token as npm publish)
+```
+
+> **Why Bun?** Faster installs, a single binary, and `bun publish` works natively with the existing
+> `.npmrc` / GH Packages setup. Tests still run through vitest (`bun run test`) because the vitest
+> suite uses `better-sqlite3` native bindings which are not yet compatible with Bun's own test runner.
+
+---
+
+## Status
+
+**v0.1.0** — Waves 1-4 of the implementation plan completed.
+
+- Wave 1: SQLite schema, migration runner, FTS5, sqlite-vec, ingest endpoint, Fastify server, CLI skeleton.
+- Wave 2: Job worker loop, hybrid search, service install adapters, Ollama + Azure providers.
+- Wave 3: 8-stage distillation pipeline, budget tracker, Zod-validated extraction.
+- Wave 4: Install wizard, cross-OS CI matrix, E2E plugin integration test, this documentation.
+
+Spec: [astramemory-plugin/docs/superpowers/specs/2026-06-27-astramemory-local-v1-design.md](../astramemory-plugin/docs/superpowers/specs/2026-06-27-astramemory-local-v1-design.md)

package/dist/backup/retention.d.ts

@@ -0,0 +1,15 @@
+export interface RetentionResult {
+    kept: string[];
+    deleted: string[];
+}
+/**
+ * Prune old backup snapshots in `dir`, keeping the newest `keep` files.
+ *
+ * Only files matching `memory-*.sqlite` are considered — other files in the
+ * directory are left untouched.
+ *
+ * @param dir  Directory to scan (must exist; throws if not readable).
+ * @param keep Number of snapshots to retain (must be >= 1).
+ * @returns    { kept, deleted } arrays of absolute paths.
+ */
+export declare function pruneOldBackups(dir: string, keep: number): RetentionResult;

package/dist/backup/retention.js

@@ -0,0 +1,62 @@
+/**
+ * retention.ts — prune old backup snapshots, keeping the newest N.
+ *
+ * Scans `dir` for files matching `memory-*.sqlite`, sorts by mtime descending,
+ * keeps the first `keep`, deletes the rest.
+ */
+import { readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Prune old backup snapshots in `dir`, keeping the newest `keep` files.
+ *
+ * Only files matching `memory-*.sqlite` are considered — other files in the
+ * directory are left untouched.
+ *
+ * @param dir  Directory to scan (must exist; throws if not readable).
+ * @param keep Number of snapshots to retain (must be >= 1).
+ * @returns    { kept, deleted } arrays of absolute paths.
+ */
+export function pruneOldBackups(dir, keep) {
+    if (keep < 1)
+        throw new RangeError(`keep must be >= 1, got ${keep}`);
+    // Gather candidate files
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        // Directory does not exist yet — nothing to prune
+        return { kept: [], deleted: [] };
+    }
+    const candidates = entries
+        .filter(name => /^memory-.*\.sqlite$/.test(name))
+        .map(name => {
+        const fullPath = join(dir, name);
+        let mtime = 0;
+        try {
+            mtime = statSync(fullPath).mtimeMs;
+        }
+        catch {
+            // File vanished between readdir and stat — skip it
+            return null;
+        }
+        return { path: fullPath, mtime };
+    })
+        .filter((x) => x !== null);
+    // Sort newest first
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    const kept = candidates.slice(0, keep).map(c => c.path);
+    const toDelete = candidates.slice(keep);
+    const deleted = [];
+    for (const candidate of toDelete) {
+        try {
+            unlinkSync(candidate.path);
+            deleted.push(candidate.path);
+        }
+        catch {
+            // Best-effort: if deletion fails (e.g. race condition) skip it
+        }
+    }
+    return { kept, deleted };
+}
+//# sourceMappingURL=retention.js.map

package/dist/backup/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/backup/retention.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOjC;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,IAAY;IACvD,IAAI,IAAI,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IAErE,yBAAyB;IACzB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,kDAAkD;QAClD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,UAAU,GAAG,OAAO;SACvB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAChD,GAAG,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,CAAC;YACH,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAwC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAEnE,oBAAoB;IACpB,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAE7C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/backup/snapshot.d.ts

@@ -0,0 +1,21 @@
+import type { DB } from '../storage/db.js';
+export interface SnapshotResult {
+    path: string;
+    size_bytes: number;
+    duration_ms: number;
+}
+/**
+ * Create an online-safe snapshot of `db` to `outPath`.
+ *
+ * The directory containing outPath is created if it does not exist.
+ * Uses db.backup() (online-safe, zero downtime) when available; falls back
+ * to `VACUUM INTO` otherwise. When `db` is an encrypted (SQLCipher) database,
+ * the backup/VACUUM INTO output is encrypted with the same key — SQLite's
+ * online backup API and VACUUM INTO both operate on the live connection's
+ * pages, so ciphertext pages are copied as ciphertext (SEC-8).
+ *
+ * @param db      An open better-sqlite3-multiple-ciphers Database instance.
+ * @param outPath Absolute destination path for the snapshot file.
+ * @returns       Metadata about the written snapshot.
+ */
+export declare function createSnapshot(db: DB, outPath: string): Promise<SnapshotResult>;

package/dist/backup/snapshot.js

@@ -0,0 +1,55 @@
+/**
+ * snapshot.ts — online-safe SQLite backup using better-sqlite3's built-in
+ * backup API (which uses the SQLite Online Backup API under the hood).
+ *
+ * Falls back to VACUUM INTO if the better-sqlite3 version does not expose
+ * db.backup().
+ */
+import { mkdirSync, statSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Create an online-safe snapshot of `db` to `outPath`.
+ *
+ * The directory containing outPath is created if it does not exist.
+ * Uses db.backup() (online-safe, zero downtime) when available; falls back
+ * to `VACUUM INTO` otherwise. When `db` is an encrypted (SQLCipher) database,
+ * the backup/VACUUM INTO output is encrypted with the same key — SQLite's
+ * online backup API and VACUUM INTO both operate on the live connection's
+ * pages, so ciphertext pages are copied as ciphertext (SEC-8).
+ *
+ * @param db      An open better-sqlite3-multiple-ciphers Database instance.
+ * @param outPath Absolute destination path for the snapshot file.
+ * @returns       Metadata about the written snapshot.
+ */
+export async function createSnapshot(db, outPath) {
+    // Ensure parent directory exists
+    mkdirSync(dirname(outPath), { recursive: true });
+    const start = Date.now();
+    const vacuumInto = () => {
+        // VACUUM INTO is online-safe per SQLite docs (consistent snapshot, does
+        // not block writes). Under SQLite3MultipleCiphers the output inherits the
+        // main database's encryption, so ciphertext stays ciphertext (SEC-8).
+        rmSync(outPath, { force: true }); // VACUUM INTO refuses existing targets
+        db.exec(`VACUUM INTO '${outPath.replace(/'/g, "''")}'`);
+    };
+    if (typeof db.backup === 'function') {
+        // better-sqlite3 >= 7.6 exposes db.backup(path) which uses the
+        // SQLite Online Backup API — safe to run while the DB is in use.
+        // On an ENCRYPTED connection the cipher driver rejects the plaintext
+        // target with "backup is not supported with incompatible source and
+        // target databases" — fall back to VACUUM INTO in that case.
+        try {
+            await db.backup(outPath);
+        }
+        catch {
+            vacuumInto();
+        }
+    }
+    else {
+        vacuumInto();
+    }
+    const duration_ms = Date.now() - start;
+    const { size: size_bytes } = statSync(outPath);
+    return { path: outPath, size_bytes, duration_ms };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/backup/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/backup/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,OAAe;IAEf,iCAAiC;IACjC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEjD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEzB,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,wEAAwE;QACxE,0EAA0E;QAC1E,sEAAsE;QACtE,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,uCAAuC;QACzE,EAAE,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEF,IAAI,OAAQ,EAAU,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAC7C,+DAA+D;QAC/D,iEAAiE;QACjE,qEAAqE;QACrE,oEAAoE;QACpE,6DAA6D;QAC7D,IAAI,CAAC;YACH,MAAO,EAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,EAAE,CAAC;QACf,CAAC;IACH,CAAC;SAAM,CAAC;QACN,UAAU,EAAE,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IACvC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAE/C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AACpD,CAAC"}

package/dist/backup/verify.d.ts

@@ -0,0 +1,23 @@
+import type { DB } from '../storage/db.js';
+export interface VerifyResult {
+    ok: boolean;
+    integrity: string;
+    counts: {
+        memories: {
+            live: number;
+            snapshot: number;
+        };
+        transcripts: {
+            live: number;
+            snapshot: number;
+        };
+    };
+    error?: string;
+}
+/**
+ * Verify `snapshotPath` against the live `db` it was snapshotted from.
+ * Row-count tolerance: the live DB may have gained rows since the snapshot
+ * started (online backup), so snapshot counts must be <= live counts and
+ * within `tolerance` of them — never greater, never wildly behind.
+ */
+export declare function verifySnapshot(liveDb: DB, snapshotPath: string, key?: string, tolerance?: number): VerifyResult;