@hilbras/remembra 3.5.0 → 3.7.0

package/docs/observability.md

@@ -0,0 +1,120 @@
+# Observability
+
+Structured logging, Prometheus metrics, health/readiness, and alert rules.
+Added in **3.7.0** (Phase 7 of the deep audit).
+
+## Structured logging
+
+Every server-side event goes through one logger (`src/log.ts`) and lands on
+**stderr** — stdout stays reserved for MCP stdio framing and CLI output.
+
+| | |
+|---|---|
+| **Format selection** | `REMEMBRA_LOG=json` or `REMEMBRA_LOG=text` forces a format. Unset → **auto**: JSON when stderr is piped/redirected (containers, CI, log shippers), text on a TTY. |
+| **JSON shape** | `{"ts","level","event","msg",...fields}` — one object per line, ready for any log shipper. |
+| **Text shape** | The human message verbatim (the exact strings Remembra always printed). |
+| **Hygiene** | Raw search query text and the storage root path are included **only under `REMEMBRA_DEBUG=1`** (Phase 2 log-hygiene rule). |
+
+Example JSON events:
+
+```json
+{"ts":"2026-09-23T05:53:50.366Z","level":"info","event":"search","terms":2,"results":2,"duration_ms":1}
+{"ts":"2026-09-23T05:53:50.314Z","level":"info","event":"http_listening","msg":"Remembra HTTP API listening on 0.0.0.0:8787 (auth required)","port":8787,"host":"0.0.0.0","auth":true}
+{"ts":"…","level":"warn","event":"memory_parse_skipped","file":"bad.md","reason":"missing frontmatter"}
+```
+
+Event names in the wild: `http_listening`, `mcp_listening`, `search`,
+`shutdown`, `crash_recovery`, `memory_parse_skipped`, `embedding_failed`,
+`touch_failed`, `merge_llm_failed`, `decay_failed`.
+
+## Metrics — `GET /metrics`
+
+Prometheus text exposition (format 0.0.4), served by the **same binary**.
+
+**Auth:** the endpoint sits *after* the API-key check — keyed (including
+public) deployments require `x-api-key` (or `Authorization: Bearer`); an
+unkeyed server is loopback-only by the default-deny rule anyway. `/health`
+stays exempt so unauthenticated readiness probes keep working.
+
+| Series | Type | Labels | Meaning |
+|---|---|---|---|
+| `remembra_http_requests_total` | counter | `route`, `method`, `status` | Requests. `route` is a fixed low-cardinality label (`health`/`metrics`/`memories`/`search`/`digest`/`maintain`/`memory_item`/`other`) — never the raw path. |
+| `remembra_http_request_duration_seconds` | histogram | `route` | Request latency. |
+| `remembra_errors_total` | counter | `code`, `transport` | Classified errors (`http`/`mcp`). Codes: the [error codes](architecture.md#error-classification-audit-phase-2) plus `INVALID_INPUT`, `PAYLOAD_TOO_LARGE`, `INTERNAL`. |
+| `remembra_searches_total` | counter | — | `memory_search` invocations. |
+| `remembra_search_duration_seconds` | histogram | — | Search latency (embed + walk + score + rank). |
+| `remembra_stores_total` | counter | — | `memory_store` invocations. |
+| `remembra_digests_total` | counter | — | Completed session-digest runs. |
+| `remembra_digest_items_total` | counter | `result` | Digest items: `stored` / `skipped` / `merged`. |
+| `remembra_digest_duration_seconds` | histogram | — | Digest run latency (includes lock queueing). |
+| `remembra_cache_events_total` | counter | `result` | Parse-cache probes: `hit` / `miss`. |
+| `remembra_cache_entries` | gauge | — | Parse-cache entries currently held. |
+| `remembra_info` | gauge | `version` | Build info, always `1`. |
+
+### Scrape config
+
+```yaml
+scrape_configs:
+  - job_name: remembra
+    metrics_path: /metrics
+    static_configs:
+      - targets: ["127.0.0.1:8787"]
+    # Required when REMEMBRA_API_KEY is set:
+    headers:
+      x-api-key: YOUR_KEY
+```
+
+## Health — `GET /health`
+
+No auth (readiness probes carry no key). Liveness **and** readiness in one:
+
+- `200 {"status":"ok", "version", "uptime_s", "storage":"ok", "cache":{...}}`
+  when a full store read succeeds.
+- `503 {"status":"unready", "storage":"<ERROR_CODE>", ...}` when storage cannot
+  be read — the probe **fails instead of lying**.
+
+## Alerting
+
+Remembra ships the *substrate* (counters + scrape endpoint), not a notifier —
+alerting is Prometheus/Grafana's job. Ready-to-paste rules:
+
+```yaml
+groups:
+  - name: remembra
+    rules:
+      - alert: RemembraDown
+        expr: up{job="remembra"} == 0
+        for: 2m
+        annotations:
+          summary: Remembra target unreachable
+
+      - alert: RemembraHighInternalErrorRate
+        expr: sum(rate(remembra_errors_total{code=~"IO_ERROR|INTERNAL|LLM_ERROR"}[5m])) > 0.1
+        for: 5m
+        annotations:
+          summary: >-
+            {{ $value | humanize }} internal errors/s — storage or provider
+            failures (client 4xx are excluded on purpose)
+
+      - alert: RemembraReadinessFailing
+        expr: increase(remembra_http_requests_total{route="health",status="503"}[5m]) > 0
+        annotations:
+          summary: /health returning 503 (storage unready)
+
+      - alert: RemembraLockContention
+        expr: increase(remembra_errors_total{code="LOCK_TIMEOUT"}[15m]) > 5
+        annotations:
+          summary: Repeated lock timeouts — concurrent writers starving
+
+      - alert: RemembraSlowSearches
+        expr: histogram_quantile(0.95, rate(remembra_search_duration_seconds_bucket[5m])) > 1
+        annotations:
+          summary: Search p95 above 1s
+
+      - alert: RemembraCacheThrash
+        expr: |
+          sum(rate(remembra_cache_events_total{result="miss"}[15m]))
+            / sum(rate(remembra_cache_events_total[15m])) > 0.5
+        annotations:
+          summary: Parse-cache hit ratio below 50% — store churn or capacity
+```

package/docs/providers.md

@@ -84,8 +84,8 @@ With `REMEMBRA_EMBEDDINGS=openai|ollama`:
   frontmatter (`embedding: [...]`) — computed once, never re-embedded.
 - **On search**: the query is embedded and **cosine similarity becomes the
   primary ranking signal**. Importance and recency remain small modifiers.
-- **Gates stay absolute**: `role` memories always surface, and memories from
-  other scopes are never returned, no matter how similar.
+- **Gates stay absolute**: in-scope `role` memories always surface, and
+  memories from other scopes are never returned, no matter how similar.
 - **Memories without vectors** (stored while embeddings were off) fall back
   to keyword matching.
 

package/docs/security.md

@@ -23,13 +23,16 @@ and how to deploy safely.
 
 ### Role memories are instructions — the prompt-injection surface
 
-`role` memories always surface (+1000) and are meant to be **followed**, not
-merely recalled. That is the feature — and the risk:
+`role` memories always surface (+1000) **within their scope** and are meant
+to be **followed**, not merely recalled. That is the feature — and the risk:
 
 - **Via MCP**: whoever can call `memory_store` in your session is already the
   agent you're running. No additional boundary is crossed.
 - **Via HTTP**: anyone with your API key can plant a global `role` that every
   future session will receive as an instruction.
+- **Cross-project**: roles scoped to another project do *not* surface in your
+  searches (isolation, enforced since 3.6.0) — the residual vector is a
+  `global` role, which reaches every scope by design.
 
 **Rules:**
 1. Never expose HTTP without `REMEMBRA_API_KEY` (enforced — see below).
@@ -52,11 +55,12 @@ Retrieved memories should be treated as **data with provenance**, not commands
 | **Body size limit** | 10 MiB default (`REMEMBRA_MAX_BODY`), `413` on excess — pre-checks `Content-Length` and enforces while streaming |
 | **Digest validation** | `DigestInput` Zod schema on both MCP and HTTP paths |
 | **Atomic writes** | temp file + `rename()` (POSIX-atomic) — no half-written memories after a crash |
-| **Advisory locking** | `<root>/.remembra.lock` (`O_EXCL`) + in-process FIFO — cross-process writes serialize; stale locks (dead pid / older than `REMEMBRA_LOCK_STALE_MS`) are stolen; waiters fail with typed `LOCK_TIMEOUT` (HTTP 423) |
+| **Advisory locking** | `<root>/.remembra.lock` (`O_EXCL`) + in-process FIFO — cross-process writes serialize; stale locks (dead pid / older than `REMEMBRA_LOCK_STALE_MS`) are stolen; a fresh lock with this process's own pid is treated as a live sibling instance and waited on; waiters fail with typed `LOCK_TIMEOUT` (HTTP 423) |
 | **Crash recovery** | one-time pass on first access: removes orphaned `*.tmp`, reconciles ids left in both active+archived trees by an interrupted archive/revive |
 | **Structured errors** | every actionable failure has a stable code (`INVALID_INPUT`, `LOCK_TIMEOUT`, `LLM_ERROR`, …) mapped to HTTP statuses / MCP `[CODE]` prefixes |
 | **ID collisions** | 12-hex IDs (2⁴⁸) + existence check on store |
 | **Content-Length** | Set on every response |
+| **Metrics auth (3.7.0)** | `GET /metrics` sits *after* the API-key check — counters and latencies never leak without the key (`/health` stays exempt for readiness probes) |
 
 ## Deployment checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/remembra",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "description": "External memory for AI assistants — remember facts, decisions, roles and history across sessions. MCP server for OpenCode, Claude Code, Cline, Kimi Code and more.",
   "type": "module",
   "bin": {