@hilbras/remembra 3.0.0 → 3.2.0

package/dist/types.js

@@ -1,12 +1,98 @@
 import { z } from "zod";
 /** The four memory types Remembra stores. */
 export const MemoryType = z.enum(["fact", "decision", "role", "history"]);
-export const StoreInput = z.object({
-    type: MemoryType,
-    content: z.string().min(1),
-    scope: z.string().default("global"),
-    tags: z.array(z.string()).default([]),
-    importance: z.number().int().min(1).max(5).default(3),
-    source: z.string().optional(),
+/**
+ * Frontmatter schema version. Bump when the Memory format changes and
+ * add a migration step in store.ts (missing field in old files = v1).
+ */
+export const SCHEMA_VERSION = 1;
+/**
+ * Scope safety: reject `..` path segments so scope can never escape the
+ * storage root (P0 directory traversal fix). Absolute paths like
+ * `/home/user/project` are fine — path.join keeps them contained.
+ */
+export function isSafeScope(scope) {
+    if (scope === "global")
+        return true;
+    const normalized = scope.replace(/[^a-zA-Z0-9._/-]/g, "_");
+    return !normalized.split("/").some((seg) => seg === "..");
+}
+// ---------------------------------------------------------------------------
+// Shared input schemas (audit #13: one source of truth).
+// The raw `*Shape` objects feed MCP tool inputSchemas (ZodRawShape);
+// the parsed `*Input` objects validate on every transport.
+// ---------------------------------------------------------------------------
+export const storeInputShape = {
+    type: MemoryType.describe("fact | decision | role | history"),
+    content: z.string().min(1).describe("The memory itself, written as a standalone statement"),
+    scope: z
+        .string()
+        .default("global")
+        .describe("'global' for always-relevant memories, or a project path/id for project-scoped ones"),
+    tags: z.array(z.string()).default([]).describe("Keywords that boost retrieval"),
+    importance: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .default(3)
+        .describe("1=minor, 5=critical (default 3)"),
+    source: z.string().optional().describe("Originating session or client"),
+};
+export const StoreInput = z
+    .object(storeInputShape)
+    .refine((v) => isSafeScope(v.scope), { message: "scope must not contain '..' path segments" });
+export const digestInputShape = {
+    transcript: z
+        .string()
+        .min(1)
+        .describe("Conversation transcript or a detailed summary of the session"),
+    scope: z.string().optional().describe("Scope for extracted memories (default: global)"),
+    source: z.string().optional().describe("Originating session/client"),
+};
+export const DigestInput = z
+    .object(digestInputShape)
+    .refine((v) => v.scope === undefined || isSafeScope(v.scope), {
+    message: "scope must not contain '..' path segments",
+});
+export const searchInputShape = {
+    query: z.string().optional().describe("Keywords to match (omit to get a scope/recency-ranked list)"),
+    scope: z.string().optional().describe("Current project path or workspace id to filter by"),
+    type: MemoryType.optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+};
+export const SearchInput = z.object(searchInputShape);
+export const listInputShape = {
+    scope: z.string().optional(),
+    type: MemoryType.optional(),
+    includeArchived: z.boolean().optional().describe("Include archived memories (flagged)"),
+};
+export const ListInput = z.object(listInputShape);
+export const forgetInputShape = {
+    id: z.string().describe("Memory id (from memory_store or memory_list)"),
+};
+export const ForgetInput = z.object(forgetInputShape);
+/** Backup file envelope (remembra export / import). */
+export const SNAPSHOT_FORMAT = "remembra-export";
+export const SnapshotInput = z.object({
+    format: z.literal(SNAPSHOT_FORMAT),
+    version: z.number().int().positive(),
+    exportedAt: z.string(),
+    memories: z
+        .array(z.object({
+        id: z.string().regex(/^[a-f0-9]{8,32}$/, "invalid id"),
+        type: MemoryType,
+        content: z.string().min(1),
+        scope: z.string().refine(isSafeScope, { message: "scope must not contain '..'" }),
+        tags: z.array(z.string()),
+        importance: z.number().int().min(1).max(5),
+        createdAt: z.string(),
+        updatedAt: z.string(),
+        source: z.string().optional(),
+        lastSeen: z.string().optional(),
+        archivedAt: z.string().optional(),
+        embedding: z.array(z.number()).optional(),
+    }))
+        .max(100_000),
 });
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,6CAA6C;AAC7C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AA4B1E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC9B,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/chatgpt.md

@@ -19,7 +19,9 @@ curl http://localhost:8787/health
 # {"status": "ok"}
 ```
 
-- `REMEMBRA_API_KEY` **strongly recommended** — without it every endpoint is open.
+- `REMEMBRA_API_KEY` **mandatory for public exposure** — without it the server
+  binds to `127.0.0.1` only, and a non-loopback `REMEMBRA_HOST` without a key
+  refuses to start (default-deny, see [security.md](security.md)).
 - The server binds to localhost by default. For ChatGPT to reach it you must expose it
   publicly (see [§4](#4-exposing-the-server)).
 

package/docs/clients.md

@@ -90,6 +90,9 @@ REMEMBRA_API_KEY="your-secret" remembra --http
 | `REMEMBRA_EMBEDDINGS` | `none` | Semantic search: `openai` \| `ollama` \| `none` |
 | `REMEMBRA_ARCHIVE_AFTER_DAYS` | `90` | Unused active memory → archived |
 | `REMEMBRA_ARCHIVE_TTL_DAYS` | `365` | Archived memory → deleted |
+| `REMEMBRA_HOST` | *(see security.md)* | HTTP bind address (loopback without key) |
+| `REMEMBRA_MAX_BODY` | `10485760` | Max HTTP request body bytes |
+| `REMEMBRA_DEBUG` | *(unset)* | `1` logs the storage root path at startup (off by default: log hygiene) |
 
 LLM/embedding key setup: see **[providers.md](providers.md)**.
 

package/docs/security.md

@@ -0,0 +1,89 @@
+# Security & Trust Model
+
+Remembra v3.1.0 hardening notes — what's protected, what's a trust decision,
+and how to deploy safely.
+
+## Trust model
+
+```
+┌─ Trusted ─────────────────────────────────────────────┐
+│  You / your MCP clients (OpenCode, Claude Code, ...)  │
+│  The LLM you configure for digest/merge               │
+│  Files under REMEMBRA_HOME (local filesystem trust)   │
+└───────────────────────────────────────────────────────┘
+┌─ Semi-trusted ────────────────────────────────────────┐
+│  Transcripts passed to memory_digest                  │
+│  Anyone holding your REMEMBRA_API_KEY                 │
+└───────────────────────────────────────────────────────┘
+┌─ Untrusted ───────────────────────────────────────────┐
+│  Network peers (if HTTP is exposed)                   │
+│  Memory content written by other users of shared AI   │
+└───────────────────────────────────────────────────────┘
+```
+
+### 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:
+
+- **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.
+
+**Rules:**
+1. Never expose HTTP without `REMEMBRA_API_KEY` (enforced — see below).
+2. Treat the API key as root access to your assistant's standing instructions.
+3. Audit roles periodically: `memory_list { type: "role", includeArchived: true }`.
+4. If you ingest transcripts from other people (shared ChatGPT GPT, public bot),
+   remember the digest LLM can extract `role` items from *their* text — review
+   before trusting a multi-user deployment.
+
+Retrieved memories should be treated as **data with provenance**, not commands
+— but Remembra cannot enforce how the consuming model interprets them.
+
+## Enforced protections (3.1.0)
+
+| Protection | Mechanism |
+|------------|-----------|
+| **Directory traversal (P0)** | Scopes containing `..` rejected by Zod (`StoreInput`/`DigestInput`) + `fileFor()` re-verifies the resolved path stays under `REMEMBRA_HOME` (defense in depth) |
+| **Default-deny HTTP** | Without `REMEMBRA_API_KEY`: binds `127.0.0.1` only. Non-loopback `REMEMBRA_HOST` without a key → **refuses to start** |
+| **Timing-safe auth** | API keys compared with `crypto.timingSafeEqual` |
+| **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 |
+| **ID collisions** | 12-hex IDs (2⁴⁸) + existence check on store |
+| **Content-Length** | Set on every response |
+
+## Deployment checklist
+
+```bash
+# Local (safe default — loopback, key optional)
+remembra --http
+
+# Public (ChatGPT etc.) — key is mandatory
+export REMEMBRA_API_KEY="$(openssl rand -hex 32)"
+export REMEMBRA_HOST=0.0.0.0
+remembra --http
+# → put TLS in front (Caddy/nginx/cloudflared). Remembra speaks plain HTTP.
+```
+
+- [ ] `REMEMBRA_API_KEY` set with a long random value (≥32 bytes)
+- [ ] TLS terminator in front for any non-loopback exposure
+- [ ] `REMEMBRA_HOME` lives on a filesystem you back up — use
+      `remembra export <file>.json` for portable snapshots (or `rsync`/git the
+      directory)
+- [ ] Periodic `memory_list {type: "role"}` audit
+- [ ] LLM/embedding keys scoped to least privilege
+
+## Known non-goals (current version)
+
+- **No multi-tenancy** — one store per installation; scope isolates *projects*,
+  not *users*. Never share one instance between mutually untrusting users.
+- **No encryption at rest** — files are plaintext markdown (by design: you can
+  read and edit them). Use filesystem-level encryption if needed.
+- **No PII redaction** — what you store is what's written to disk.
+- **No write locking / journal** — single-writer assumption; concurrent writers
+  from multiple machines are unsupported (atomic writes + the digest lock
+  protect against crashes and same-process races, not cross-machine
+  interleaving). `remembra export` for backups across machines.

package/docs/tools.md

@@ -88,6 +88,17 @@ vectors. Roles never decay. Takes no arguments. See [lifecycle.md](lifecycle.md)
 Returns counts + affected ids. Also available as `POST /maintain` and the
 `remembra maintain` CLI command.
 
+## CLI commands
+
+```bash
+remembra maintain            # decay sweep + vector backfill (one-shot, prints JSON)
+remembra export <file>.json  # full backup snapshot incl. archived memories
+remembra import <file>.json  # restore; validates whole file first (atomic), idempotent
+```
+
+Import skips existing ids and exact-duplicate contents, so running it twice —
+or importing into a machine that already has the data — is always safe.
+
 ---
 
 ## Suggested session flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/remembra",
-  "version": "3.0.0",
+  "version": "3.2.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": {