@hilbras/remembra 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -7,6 +7,127 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 > (3.0.0 = v3). Earlier releases used independent semver: 0.1.0 = v1,
 > 0.2.0 = v1.5, 0.3.0 = v2, 0.4.0 = v3.
 
+## [3.8.0] — 2026-09-23
+
+**Phase 8 of the deep audit — Advanced Capabilities.** All five roadmap
+items covered; both storage-altering features are **opt-in** (scope review:
+plain markdown and byte-faithful storage remain the defaults).
+
+### Added
+- **Relationship graph** — `related: [ids]` frontmatter (directed, single
+  write; backlinks derived at read time), `memory_relate` MCP tool
+  (add/remove, targets validated, self-links rejected, idempotent), plus the
+  missing read surfaces: **`memory_get`** / `GET /memories/:id` return a
+  memory with resolved `related` + `backlinks`. Retrieval ranking untouched —
+  graph is structure for the consumer, not a score.
+- **Confidence scores** — `confidence: 0–1` frontmatter: explicit stores
+  default `1.0`, digest extractions `0.7` (the extraction LLM may supply its
+  own via the extended prompt/schema). Surfaced everywhere and carried through
+  merge/export/import; **deliberately not ranked** — importance answers
+  "relevant?", confidence answers "true?" (Phase 4 weight decisions stay
+  closed).
+- **PII redaction filter** (opt-in `REMEMBRA_REDACT=1`) — pattern filter at
+  the *ingest layer* (`memory_store`, digest items, merge output): emails,
+  Luhn-valid cards, SSNs, phone numbers, provider tokens / ≥40-char entropy
+  blobs → typed placeholders (`<EMAIL>` …). Cards must pass Luhn; phone
+  matching requires separators + 10–15 digits, so dates/versions never match.
+  Irreversible by design; `remembra_redactions_total{kind}` + `redacted`
+  log event (counts only, never matched text). Reverses the former "no PII
+  filter" non-goal — documented with its limits in `docs/security.md`.
+- **Encrypted storage mode** (opt-in `REMEMBRA_ENCRYPT_KEY`) — AES-256-GCM
+  per file via `node:crypto` (zero deps): magic-header detection, transparent
+  decrypt-on-read, encrypt-on-write, mixed plain/cipher trees supported;
+  `remembra encrypt` / `remembra decrypt` migrate the whole tree (incl.
+  history) idempotently under the advisory lock. Missing/wrong key fails
+  **loudly**: `ENCRYPTED_NO_KEY` (HTTP 503, `/health` `storage` field) —
+  never warn-skipped into silent partial results. GCM makes wrong-key ≡
+  tampered. Reverses the former "no encryption at rest" non-goal with an
+  explicit threat-model section (protects stolen backups / copied dirs, not
+  a runtime attacker with your env).
+- **Diff/history view** — content-changing updates snapshot the raw
+  on-disk pre-image into `.history/<id>/<epochMs>-<seq>.md` first (content-
+  equality gate: embedding backfills and linking never snapshot);
+  `memory_history` MCP tool + `GET /memories/:id/history?limit=` return
+  versions newest-first, each with a **unified line diff** against its
+  predecessor (own ~60-line LCS, zero deps, cell-budget fallback for huge
+  contents). Pruned to `REMEMBRA_HISTORY_LIMIT` (default 20, `0` disables);
+  `.history` is never walked by `all()`/search.
+
+### Changed
+- Error classification gains `ENCRYPTED_NO_KEY` (503) and documents why it
+  breaks the skip-malformed-file rule; `metrics` route enum gains
+  `memory_sub` (the relate/history sub-routes).
+- Extraction system prompt optionally returns `confidence` (0–1).
+
+### Docs
+`tools` (+3 tools, 9 total, encrypt/decrypt CLI), `memory-model`
+(relationships, version history, metadata rows, layout incl. `.history`),
+`security` (encryption + redaction sections replace the two reversed
+non-goals, checklist items), `architecture` (encryption format, history
+snapshot design, error table), `clients` (+3 env vars), `observability`
+(+4 counters, `memory_sub`, `redacted` event), `chatgpt` (+3 routes),
+`lifecycle` (merge → history cross-ref), README (9 tools, 11 routes).
+
+### Tests
+- **148 tests** (+16: redaction patterns + false-positive guards + service
+  on/off, digest redaction & confidence pass-through, confidence round-trip,
+  relations incl. backlinks/validation/idempotence/persistence, diff unit,
+  merge → snapshot → diff view, embedding-gate + limit pruning, encryption
+  round-trip / missing-key loud failure / wrong-key / mixed trees /
+  idempotent both-way migration incl. history, HTTP GET/relate/history
+  routes + `memory_sub` metric label). Suite verified stable across 3
+  consecutive runs.
+
+## [3.7.0] — 2026-09-23
+
+**Phase 7 of the deep audit** — observability. All five roadmap items
+covered (error-rate alerting taken as the *pragmatic substrate*: counters +
+documented rules, no built-in notifier — decided in scope review).
+
+### Added
+- **Structured JSON logging** (`src/log.ts`) — every server-side event goes
+  through one logger on **stderr** (stdout stays reserved for MCP stdio/CLI).
+  Format: `REMEMBRA_LOG=json|text` forces it; unset → auto — JSON when stderr
+  is piped (containers, CI, shippers), text on a TTY. Text mode prints the
+  exact legacy strings, so existing greps and the Phase 2/3 tests still hold.
+  JSON lines carry `{"ts","level","event","msg",...fields}`.
+- **`GET /metrics`** (`src/metrics.ts`) — zero-dependency Prometheus text
+  endpoint: request/digest/search/cache counters, latency histograms,
+  `errors_total{code,transport}`, cache-entry gauge, `remembra_info`. Route
+  labels are a fixed low-cardinality enum (never raw paths). Sits **after**
+  the API-key check — keyed deployments must not leak counters; `/health`
+  stays exempt.
+- **Search query logging** — one structured `search` event per call (scope,
+  term count, results, limit, `duration_ms`). Raw query text only under
+  `REMEMBRA_DEBUG` (Phase 2 log-hygiene rule unchanged).
+- **`/health` readiness probe** — now runs a real storage read: `200 ok`
+  with `version`/`uptime_s`/`storage`/`cache` fields, **`503 unready`** with
+  the failing error code when storage cannot be read — the probe fails
+  instead of lying. Field `status:"ok"` kept for existing consumers.
+- **Alerting infrastructure** — `docs/observability.md`: metric reference,
+  scrape config (incl. `x-api-key`), and ready-to-paste Prometheus rules
+  (down, internal error rate with 4xx excluded, readiness, lock contention,
+  search p95, cache thrash). No built-in notifier by design: a local tool
+  alerts through the operator's existing stack.
+- `src/version.ts` single-sources `VERSION` (MCP server id, `/health`,
+  `remembra_info`); a test pins it to `package.json`.
+
+### Fixed
+- **Prometheus bucket labels** — histogram series emitted `{le="…"route="…"}`
+  (missing comma), caught by the exposition-format test.
+
+### Changed
+- Conversion to `logEvent` at 8 sites (listening banners, shutdown, parse
+  skip, crash recovery, embedding/touch/merge/decay failures) — messages
+  unchanged in text mode.
+
+### Tests
+- **132 tests** (+13: log formats + auto-detection, `/metrics` content,
+  label enum + exposition grammar, auth on `/metrics`, counter movement for
+  store/search/cache, MCP + HTTP error counters, hygiene-first query logging
+  (and `REMEMBRA_DEBUG` opt-in), healthy + broken-storage `/health`,
+  version pin). Suite verified stable across 3 consecutive runs.
+
 ## [3.6.0] — 2026-09-23
 
 **Phase 6 of the deep audit** — testing depth. All six roadmap items now

package/README.md

@@ -85,10 +85,14 @@ Then wire a Custom GPT to the API — full walkthrough in **[docs/chatgpt.md](do
 
 | Method | Route | Purpose |
 |--------|-------|---------|
-| GET | `/health` | Liveness (no auth) |
+| GET | `/health` | Liveness + readiness (no auth) |
+| GET | `/metrics` | Prometheus metrics (auth when keyed) |
 | POST | `/memories` | Store a memory |
 | GET | `/memories/search?query=&scope=` | Search |
 | GET | `/memories?scope=&type=` | List |
+| GET | `/memories/:id` | One memory + related links + backlinks |
+| POST | `/memories/:id/relate` | Link / unlink memories |
+| GET | `/memories/:id/history` | Version history with line diffs |
 | POST | `/memories/digest` | LLM extract + store from a transcript |
 | POST | `/maintain` | Decay sweep + vector backfill |
 | DELETE | `/memories/:id` | Forget |
@@ -123,6 +127,9 @@ tampered snapshot is rejected atomically, never half-imported. Of course,
 | `memory_digest` | Extract + store memories from a transcript (LLM) |
 | `memory_search` | Retrieve relevant memories (pass `scope` = current project) |
 | `memory_list` | Browse stored memories |
+| `memory_get` | Fetch one memory with its links and backlinks |
+| `memory_relate` | Link / unlink memories (relationship graph) |
+| `memory_history` | Version history of a memory with line diffs |
 | `memory_maintain` | Archive decayed / delete expired / backfill vectors |
 | `memory_forget` | Delete by id |
 
@@ -139,6 +146,7 @@ Full reference: **[docs/tools.md](docs/tools.md)**
 | [AI providers](docs/providers.md) | Digest LLM + embeddings configuration |
 | [Lifecycle](docs/lifecycle.md) | Decay, archiving, auto-delete, contradiction merging |
 | [Security](docs/security.md) | Trust model, enforced protections, deployment checklist |
+| [Observability](docs/observability.md) | Structured logs, Prometheus metrics, health/readiness, alert rules |
 | [Architecture](docs/architecture.md) | Backend interface, locking, crash recovery, error codes |
 | [Contributing](CONTRIBUTING.md) | Dev workflow and guidelines |
 | [Changelog](CHANGELOG.md) | Release history |

package/dist/backend.d.ts

@@ -1,4 +1,14 @@
 import type { Memory, StoreInput } from "./types.js";
+/** One superseded pre-image from `.history/<id>/` (audit Phase 8). */
+export interface HistoryEntry {
+    /** Snapshot file name (`${epochMs}-${seq}.md`). */
+    file: string;
+    /** The pre-image's own `updatedAt` — when this version was current. */
+    at?: string;
+    /** When the snapshot was taken (from the file name's epoch prefix). */
+    snapshotAt?: string;
+    content: string;
+}
 /**
  * Storage abstraction (audit: Phase 3 — separate MemoryStore abstraction to
  * enable a future DB swap).
@@ -18,6 +28,11 @@ export interface MemoryBackend {
     store(input: StoreInput, embedding?: number[], opts?: {
         provenance?: Memory["provenance"];
     }): Promise<Memory>;
+    /** Optional observability hook — the file backend exposes parse-cache stats. */
+    cacheStats?(): {
+        size: number;
+        capacity: number;
+    };
     get(id: string): Promise<Memory | null>;
     all(includeArchived?: boolean): Promise<Memory[]>;
     update(memory: Memory): Promise<Memory>;
@@ -26,4 +41,6 @@ export interface MemoryBackend {
     touch(id: string): Promise<void>;
     forget(id: string): Promise<boolean>;
     importMemory(m: Memory): Promise<boolean>;
+    /** Optional (audit Phase 8): superseded pre-images, newest first. */
+    history?(id: string): Promise<HistoryEntry[]>;
 }

package/dist/crypto.d.ts

@@ -0,0 +1,10 @@
+export declare function encryptionEnabled(): boolean;
+/** Cheap detection: does this file already hold ciphertext? */
+export declare function isEncrypted(buf: Buffer): boolean;
+export declare function encryptBuffer(plain: Buffer): Buffer;
+/**
+ * Decrypt a file buffer. Throws `ENCRYPTED_NO_KEY` when the key is missing
+ * or wrong (GCM authentication failure covers both — a tampered file must
+ * fail identically).
+ */
+export declare function decryptBuffer(buf: Buffer): Buffer;

package/dist/crypto.js

@@ -0,0 +1,77 @@
+/**
+ * Encrypted storage mode (audit Phase 8).
+ *
+ * Opt-in: `REMEMBRA_ENCRYPT_KEY` set → memory files are written as
+ * AES-256-GCM ciphertext (node:crypto — zero dependencies) and decrypted
+ * transparently on read. Unset → plain markdown, exactly as before.
+ *
+ * Key material: a 64-hex-char (32-byte) key, used directly — no KDF, no
+ * salt (a high-entropy symmetric key needs neither; per-file random nonces
+ * provide uniqueness). Generate one with:
+ *   node -p 'require("node:crypto").randomBytes(32).toString("hex")'
+ *
+ * On-disk format (files keep their .md names; detection is by magic bytes):
+ *   MAGIC(7) "RMBENC1" | nonce(12) | tag(16) | ciphertext
+ * The AAD is empty — files move between trees (archive/revive) freely.
+ *
+ * Failure mode without the key: reading an encrypted file throws
+ * `ENCRYPTED_NO_KEY` (HTTP 503, health `storage: ENCRYPTED_NO_KEY`) instead
+ * of warn-skipping — a store you cannot read must fail loudly, never
+ * silently serve partial data.
+ *
+ * Migration: `remembra encrypt` / `remembra decrypt` rewrite the tree under
+ * the storage lock (idempotent; already-converted files are skipped).
+ */
+import { randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
+import { RemembraError } from "./errors.js";
+const MAGIC = Buffer.from("RMBENC1", "ascii");
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+export function encryptionEnabled() {
+    return (process.env.REMEMBRA_ENCRYPT_KEY ?? "").length > 0;
+}
+function rawKey() {
+    const hex = process.env.REMEMBRA_ENCRYPT_KEY ?? "";
+    if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+        throw new RemembraError("INVALID_INPUT", "REMEMBRA_ENCRYPT_KEY must be 64 hex chars (32 bytes). Generate one: " +
+            `node -p 'require("node:crypto").randomBytes(32).toString("hex")'`);
+    }
+    return Buffer.from(hex, "hex");
+}
+/** Cheap detection: does this file already hold ciphertext? */
+export function isEncrypted(buf) {
+    return buf.length > MAGIC.length && buf.subarray(0, MAGIC.length).equals(MAGIC);
+}
+export function encryptBuffer(plain) {
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = createCipheriv("aes-256-gcm", rawKey(), nonce);
+    const ct = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return Buffer.concat([MAGIC, nonce, cipher.getAuthTag(), ct]);
+}
+/**
+ * Decrypt a file buffer. Throws `ENCRYPTED_NO_KEY` when the key is missing
+ * or wrong (GCM authentication failure covers both — a tampered file must
+ * fail identically).
+ */
+export function decryptBuffer(buf) {
+    if (!isEncrypted(buf))
+        return buf; // plain file first: plain mode must never throw
+    if (!encryptionEnabled()) {
+        throw new RemembraError("ENCRYPTED_NO_KEY", "storage contains encrypted memories but REMEMBRA_ENCRYPT_KEY is not set");
+    }
+    if (buf.length < MAGIC.length + NONCE_LEN + TAG_LEN + 1) {
+        throw new RemembraError("ENCRYPTED_NO_KEY", "encrypted file is truncated");
+    }
+    const nonce = buf.subarray(MAGIC.length, MAGIC.length + NONCE_LEN);
+    const tag = buf.subarray(MAGIC.length + NONCE_LEN, MAGIC.length + NONCE_LEN + TAG_LEN);
+    const ct = buf.subarray(MAGIC.length + NONCE_LEN + TAG_LEN);
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", rawKey(), nonce);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ct), decipher.final()]);
+    }
+    catch {
+        throw new RemembraError("ENCRYPTED_NO_KEY", "cannot decrypt: wrong REMEMBRA_ENCRYPT_KEY or corrupted file");
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/diff.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Line-based unified diff (audit Phase 8 — diff/history view).
+ *
+ * Zero-dependency LCS over lines producing standard unified format with 2
+ * lines of context, so any client that renders `diff -u` output renders our
+ * history view for free.
+ *
+ * Guard: the LCS table is O(n·m) — contents above the cell budget fall back
+ * to a coarse whole-block diff instead of allocating hundreds of megabytes.
+ */
+/**
+ * Unified diff of `prev` → `next`. Empty string when identical.
+ * `fromLabel`/`toLabel` name the sides (defaults: previous/current).
+ */
+export declare function unifiedDiff(prev: string, next: string, fromLabel?: string, toLabel?: string): string;

package/dist/diff.js

@@ -0,0 +1,135 @@
+/**
+ * Line-based unified diff (audit Phase 8 — diff/history view).
+ *
+ * Zero-dependency LCS over lines producing standard unified format with 2
+ * lines of context, so any client that renders `diff -u` output renders our
+ * history view for free.
+ *
+ * Guard: the LCS table is O(n·m) — contents above the cell budget fall back
+ * to a coarse whole-block diff instead of allocating hundreds of megabytes.
+ */
+const MAX_CELLS = 4_000_000;
+const CONTEXT = 2;
+function lcsOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // dp[i][j] = LCS length of a[i:], b[j:]
+    const dp = new Uint32Array((n + 1) * (m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i * (m + 1) + j] =
+                a[i] === b[j] ? dp[(i + 1) * (m + 1) + j + 1] + 1 : Math.max(dp[(i + 1) * (m + 1) + j], dp[i * (m + 1) + j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ kind: "keep", line: a[i] });
+            i++;
+            j++;
+        }
+        else if (dp[(i + 1) * (m + 1) + j] >= dp[i * (m + 1) + j + 1]) {
+            ops.push({ kind: "remove", line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ kind: "add", line: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ kind: "remove", line: a[i++] });
+    while (j < m)
+        ops.push({ kind: "add", line: b[j++] });
+    return ops;
+}
+/**
+ * Unified diff of `prev` → `next`. Empty string when identical.
+ * `fromLabel`/`toLabel` name the sides (defaults: previous/current).
+ */
+export function unifiedDiff(prev, next, fromLabel = "previous", toLabel = "current") {
+    if (prev === next)
+        return "";
+    const a = prev.split("\n");
+    const b = next.split("\n");
+    if ((a.length + 1) * (b.length + 1) > MAX_CELLS) {
+        // Coarse fallback: claim a full rewrite rather than allocating the table.
+        return [
+            `--- ${fromLabel}`,
+            `+++ ${toLabel}`,
+            `@@ -1,${a.length} +1,${b.length} @@ (diff omitted: content too large for line diff)`,
+            ...a.map((l) => `-${l}`),
+            ...b.map((l) => `+${l}`),
+        ].join("\n");
+    }
+    const ops = lcsOps(a, b);
+    const header = [`--- ${fromLabel}`, `+++ ${toLabel}`];
+    let out = header.join("\n");
+    // Group changed regions (with context) into hunks.
+    let idx = 0;
+    while (idx < ops.length) {
+        if (ops[idx].kind === "keep") {
+            idx++;
+            continue;
+        }
+        // Expand over the changed run.
+        let end = idx;
+        while (end < ops.length) {
+            if (ops[end].kind !== "keep") {
+                end++;
+                continue;
+            }
+            // Peek: a keep run shorter than 2·context followed by more changes
+            // belongs to the same hunk.
+            let run = 0;
+            let probe = end;
+            while (probe < ops.length && ops[probe].kind === "keep") {
+                run++;
+                probe++;
+            }
+            if (probe < ops.length && run <= CONTEXT * 2) {
+                end = probe; // small keep-gap: bridge it and keep consuming changes
+                continue;
+            }
+            break;
+        }
+        const start = Math.max(0, idx - CONTEXT);
+        const stop = Math.min(ops.length, end + CONTEXT);
+        // Line numbers (1-based) for the hunk header.
+        let aLine = 0;
+        let bLine = 0;
+        for (let k = 0; k < start; k++) {
+            if (ops[k].kind !== "add")
+                aLine++;
+            if (ops[k].kind !== "remove")
+                bLine++;
+        }
+        const aStart = aLine + 1;
+        const bStart = bLine + 1;
+        let aCount = 0;
+        let bCount = 0;
+        const hunk = [];
+        for (let k = start; k < stop; k++) {
+            const op = ops[k];
+            if (op.kind === "keep") {
+                hunk.push(` ${op.line}`);
+                aCount++;
+                bCount++;
+            }
+            else if (op.kind === "remove") {
+                hunk.push(`-${op.line}`);
+                aCount++;
+            }
+            else {
+                hunk.push(`+${op.line}`);
+                bCount++;
+            }
+        }
+        out += `\n@@ -${aStart},${aCount} +${bStart},${bCount} @@\n${hunk.join("\n")}`;
+        idx = stop;
+    }
+    return out + "\n";
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -1,11 +1,4 @@
-/**
- * Structured error classification (audit: Phase 2 — structured error
- * classification for store operations).
- *
- * Every failure that callers should react to carries a stable `code`.
- * HTTP maps codes to statuses; MCP tools surface them as `[CODE] message`.
- */
-export type ErrorCode = "INVALID_INPUT" | "SNAPSHOT_INVALID" | "SCOPE_ESCAPES_ROOT" | "NOT_FOUND" | "CONFLICT" | "LOCK_TIMEOUT" | "IO_ERROR" | "LLM_ERROR";
+export type ErrorCode = "INVALID_INPUT" | "SNAPSHOT_INVALID" | "SCOPE_ESCAPES_ROOT" | "NOT_FOUND" | "CONFLICT" | "LOCK_TIMEOUT" | "IO_ERROR" | "LLM_ERROR" | "ENCRYPTED_NO_KEY";
 export declare class RemembraError extends Error {
     readonly code: ErrorCode;
     constructor(code: ErrorCode, message: string, options?: {
@@ -18,6 +11,8 @@ export declare function statusFor(err: RemembraError): number;
 export declare function inputError(err: unknown, code: "INVALID_INPUT" | "SNAPSHOT_INVALID"): unknown;
 /** Uniform single-line rendering for MCP tool failures. */
 export declare function formatToolError(err: unknown): string;
+/** Stable low-cardinality label for metrics (`remembra_errors_total{code}`). */
+export declare function errorLabel(err: unknown): ErrorCode | "INVALID_INPUT" | "INTERNAL";
 /** MCP tool error result shape (structural — no SDK import needed). */
 export declare function toolFail(err: unknown): {
     content: {

package/dist/errors.js

@@ -5,6 +5,7 @@
  * Every failure that callers should react to carries a stable `code`.
  * HTTP maps codes to statuses; MCP tools surface them as `[CODE] message`.
  */
+import { metrics } from "./metrics.js";
 export class RemembraError extends Error {
     code;
     constructor(code, message, options) {
@@ -25,6 +26,7 @@ const HTTP_STATUS = {
     LOCK_TIMEOUT: 423, // Locked
     IO_ERROR: 500,
     LLM_ERROR: 502,
+    ENCRYPTED_NO_KEY: 503, // Service Unavailable — storage unreadable without the key
 };
 export function statusFor(err) {
     return HTTP_STATUS[err.code] ?? 500;
@@ -53,8 +55,17 @@ export function formatToolError(err) {
         return `[INVALID_INPUT] ${zodSummary(err)}`;
     return `[INTERNAL] ${err instanceof Error ? err.message : String(err)}`;
 }
+/** Stable low-cardinality label for metrics (`remembra_errors_total{code}`). */
+export function errorLabel(err) {
+    if (isRemembraError(err))
+        return err.code;
+    if (isZodLike(err))
+        return "INVALID_INPUT";
+    return "INTERNAL";
+}
 /** MCP tool error result shape (structural — no SDK import needed). */
 export function toolFail(err) {
+    metrics.inc("remembra_errors_total", { code: errorLabel(err), transport: "mcp" });
     return { content: [{ type: "text", text: formatToolError(err) }], isError: true };
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE3B;IADX,YACW,IAAe,EACxB,OAAe,EACf,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJf,SAAI,GAAJ,IAAI,CAAW;QAKxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,GAAG,YAAY,aAAa,CAAC;AACtC,CAAC;AAED,MAAM,WAAW,GAA8B;IAC7C,aAAa,EAAE,GAAG;IAClB,gBAAgB,EAAE,GAAG;IACrB,kBAAkB,EAAE,GAAG;IACvB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,YAAY,EAAE,GAAG,EAAE,SAAS;IAC5B,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;CACf,CAAC;AAEF,MAAM,UAAU,SAAS,CAAC,GAAkB;IAC1C,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC;AACtC,CAAC;AAED,SAAS,UAAU,CAAC,GAAkE;IACpF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IACrD,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,MAAM,MAAM,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,CAAC;AACpG,CAAC;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAK,GAA0B,CAAC,IAAI,KAAK,UAAU,CAAC;AACpG,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,IAA0C;IACjF,IAAI,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACpF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,eAAe,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;IAChE,IAAI,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,mBAAmB,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;IAChE,OAAO,cAAc,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,QAAQ,CAAC,GAAY;IAInC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -23,12 +23,16 @@ export declare function resolveListen(host: string | undefined, hasKey: boolean)
  * Minimal HTTP API over the same handlers the MCP tools use.
  *
  * Routes:
- *   GET    /health              → liveness (no auth)
+ *   GET    /health              → liveness + readiness (no auth): 200 ok / 503 unready
+ *   GET    /metrics             → Prometheus text format (auth when keyed)
  *   POST   /memories            → store a memory
  *   GET    /memories/search     → ?query=&scope=&type=&limit=
  *   GET    /memories            → ?scope=&type=&includeArchived=&offset=&limit=
  *   POST   /memories/digest     → LLM extraction
  *   POST   /maintain            → decay sweep + vector backfill
+ *   GET    /memories/:id        → one memory + related + backlinks (Phase 8)
+ *   POST   /memories/:id/relate → link/unlink memories (Phase 8)
+ *   GET    /memories/:id/history→ version history + line diffs (Phase 8)
  *   DELETE /memories/:id        → forget
  */
 export declare function createHttpServer(service: MemoryService, opts?: HttpOptions): http.Server;