@hilbras/remembra 3.1.0 → 3.3.0

package/dist/types.d.ts

@@ -2,10 +2,15 @@ import { z } from "zod";
 /** The four memory types Remembra stores. */
 export declare const MemoryType: z.ZodEnum<["fact", "decision", "role", "history"]>;
 export type MemoryType = z.infer<typeof MemoryType>;
+/**
+ * Frontmatter schema version. Bump when the Memory format changes and
+ * add a migration step in store.ts (missing field in old files = v1).
+ */
+export declare const SCHEMA_VERSION = 1;
 /**
  * Scope of a memory.
  * - "global": always relevant (user preferences, roles, general facts)
- * - any other string: project/workspace scope (e.g. a repo path or project id)
+ * - any other string: project/workspace scope (e.g. a project path or project id)
  */
 export type MemoryScope = string;
 export interface Memory {
@@ -31,10 +36,18 @@ export interface Memory {
  * `/home/user/project` are fine — path.join keeps them contained.
  */
 export declare function isSafeScope(scope: string): boolean;
-export declare const StoreInput: z.ZodObject<{
+export declare const storeInputShape: {
+    type: z.ZodEnum<["fact", "decision", "role", "history"]>;
+    content: z.ZodString;
+    scope: z.ZodDefault<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    importance: z.ZodDefault<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+};
+export declare const StoreInput: z.ZodEffects<z.ZodObject<{
     type: z.ZodEnum<["fact", "decision", "role", "history"]>;
     content: z.ZodString;
-    scope: z.ZodEffects<z.ZodDefault<z.ZodString>, string, string | undefined>;
+    scope: z.ZodDefault<z.ZodString>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     importance: z.ZodDefault<z.ZodNumber>;
     source: z.ZodOptional<z.ZodString>;
@@ -52,11 +65,30 @@ export declare const StoreInput: z.ZodObject<{
     tags?: string[] | undefined;
     importance?: number | undefined;
     source?: string | undefined;
+}>, {
+    type: "fact" | "decision" | "role" | "history";
+    content: string;
+    scope: string;
+    tags: string[];
+    importance: number;
+    source?: string | undefined;
+}, {
+    type: "fact" | "decision" | "role" | "history";
+    content: string;
+    scope?: string | undefined;
+    tags?: string[] | undefined;
+    importance?: number | undefined;
+    source?: string | undefined;
 }>;
 export type StoreInput = z.infer<typeof StoreInput>;
-export declare const DigestInput: z.ZodObject<{
+export declare const digestInputShape: {
+    transcript: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+};
+export declare const DigestInput: z.ZodEffects<z.ZodObject<{
     transcript: z.ZodString;
-    scope: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    scope: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     transcript: string;
@@ -66,11 +98,157 @@ export declare const DigestInput: z.ZodObject<{
     transcript: string;
     scope?: string | undefined;
     source?: string | undefined;
+}>, {
+    transcript: string;
+    scope?: string | undefined;
+    source?: string | undefined;
+}, {
+    transcript: string;
+    scope?: string | undefined;
+    source?: string | undefined;
 }>;
 export type DigestInput = z.infer<typeof DigestInput>;
+export declare const searchInputShape: {
+    query: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["fact", "decision", "role", "history"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+};
+export declare const SearchInput: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["fact", "decision", "role", "history"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type?: "fact" | "decision" | "role" | "history" | undefined;
+    scope?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}, {
+    type?: "fact" | "decision" | "role" | "history" | undefined;
+    scope?: string | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}>;
+export type SearchInput = z.infer<typeof SearchInput>;
+export declare const listInputShape: {
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["fact", "decision", "role", "history"]>>;
+    includeArchived: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const ListInput: z.ZodObject<{
+    scope: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["fact", "decision", "role", "history"]>>;
+    includeArchived: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type?: "fact" | "decision" | "role" | "history" | undefined;
+    scope?: string | undefined;
+    includeArchived?: boolean | undefined;
+}, {
+    type?: "fact" | "decision" | "role" | "history" | undefined;
+    scope?: string | undefined;
+    includeArchived?: boolean | undefined;
+}>;
+export type ListInput = z.infer<typeof ListInput>;
+export declare const forgetInputShape: {
+    id: z.ZodString;
+};
+export declare const ForgetInput: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export type ForgetInput = z.infer<typeof ForgetInput>;
+/** Query accepted by the retrieval layer (retrieval.ts). */
 export interface SearchQuery {
     query?: string;
     scope?: string;
     type?: MemoryType;
     limit?: number;
 }
+/** Backup file envelope (remembra export / import). */
+export declare const SNAPSHOT_FORMAT = "remembra-export";
+export declare const SnapshotInput: z.ZodObject<{
+    format: z.ZodLiteral<"remembra-export">;
+    version: z.ZodNumber;
+    exportedAt: z.ZodString;
+    memories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<["fact", "decision", "role", "history"]>;
+        content: z.ZodString;
+        scope: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodArray<z.ZodString, "many">;
+        importance: z.ZodNumber;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
+        lastSeen: z.ZodOptional<z.ZodString>;
+        archivedAt: z.ZodOptional<z.ZodString>;
+        embedding: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "fact" | "decision" | "role" | "history";
+        content: string;
+        scope: string;
+        tags: string[];
+        importance: number;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        source?: string | undefined;
+        lastSeen?: string | undefined;
+        archivedAt?: string | undefined;
+        embedding?: number[] | undefined;
+    }, {
+        type: "fact" | "decision" | "role" | "history";
+        content: string;
+        scope: string;
+        tags: string[];
+        importance: number;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        source?: string | undefined;
+        lastSeen?: string | undefined;
+        archivedAt?: string | undefined;
+        embedding?: number[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    format: "remembra-export";
+    version: number;
+    exportedAt: string;
+    memories: {
+        type: "fact" | "decision" | "role" | "history";
+        content: string;
+        scope: string;
+        tags: string[];
+        importance: number;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        source?: string | undefined;
+        lastSeen?: string | undefined;
+        archivedAt?: string | undefined;
+        embedding?: number[] | undefined;
+    }[];
+}, {
+    format: "remembra-export";
+    version: number;
+    exportedAt: string;
+    memories: {
+        type: "fact" | "decision" | "role" | "history";
+        content: string;
+        scope: string;
+        tags: string[];
+        importance: number;
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        source?: string | undefined;
+        lastSeen?: string | undefined;
+        archivedAt?: string | undefined;
+        embedding?: number[] | undefined;
+    }[];
+}>;
+export type SnapshotInput = z.infer<typeof SnapshotInput>;

package/dist/types.js

@@ -1,6 +1,11 @@
 import { z } from "zod";
 /** The four memory types Remembra stores. */
 export const MemoryType = z.enum(["fact", "decision", "role", "history"]);
+/**
+ * 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
@@ -12,23 +17,82 @@ export function isSafeScope(scope) {
     const normalized = scope.replace(/[^a-zA-Z0-9._/-]/g, "_");
     return !normalized.split("/").some((seg) => seg === "..");
 }
-export const StoreInput = z.object({
-    type: MemoryType,
-    content: z.string().min(1),
+// ---------------------------------------------------------------------------
+// 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")
-        .refine(isSafeScope, { message: "scope must not contain '..' path segments" }),
-    tags: z.array(z.string()).default([]),
-    importance: z.number().int().min(1).max(5).default(3),
-    source: z.string().optional(),
-});
-export const DigestInput = z.object({
-    transcript: z.string().min(1),
-    scope: z
+        .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()
-        .refine(isSafeScope, { message: "scope must not contain '..' path segments" })
-        .optional(),
-    source: z.string().max(500).optional(),
+        .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;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IAC3D,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED,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;SACL,MAAM,EAAE;SACR,OAAO,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;IAChF,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;AAGH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,MAAM,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;SAC7E,QAAQ,EAAE;IACb,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,98 @@
+# Architecture
+
+How Remembra is put together, and where the extension seams are.
+
+```
+┌──────────────┐   ┌──────────────┐
+│ MCP tools    │   │ HTTP API     │      Transports (thin adapters)
+│ (index.ts)   │   │ (http.ts)    │
+└──────┬───────┘   └──────┬───────┘
+       │  both call the same handlers
+       ▼                  ▼
+┌──────────────────────────────────┐
+│ MemoryService (service.ts)       │  Search orchestration, digest/dedup/merge,
+│  ← depends on MemoryBackend only │  decay lifecycle, snapshots, embed/LLM fail-open
+└──────────────┬───────────────────┘
+               ▼
+┌──────────────────────────────────┐
+│ MemoryBackend (backend.ts)       │  The storage contract
+└──────────────┬───────────────────┘
+               ▼
+┌──────────────────────────────────┐
+│ MemoryStore (store.ts)           │  Plain markdown files + frontmatter
+│  .remembra lock · crash recovery │  (no database, by decision — Q5-A)
+└──────────────────────────────────┘
+```
+
+## MemoryBackend: the swap seam (audit Phase 3)
+
+`MemoryService` never touches the filesystem directly — it talks to the
+`MemoryBackend` interface (`src/backend.ts`). Today's implementation is
+`MemoryStore` (markdown files). A future SQLite/vector-DB backend only has to
+satisfy that interface; the tests include an `InMemoryBackend` proving the
+service runs unchanged against a non-file implementation.
+
+Contract highlights:
+
+- mutations must be safe under same-process **and** cross-process concurrency;
+- a memory id exists in **exactly one tree** (active or archived) at rest;
+- `importMemory` refuses ids that already exist.
+
+## Concurrency model (audit Phase 2: advisory locking)
+
+Three layers, from narrowest to widest:
+
+| Layer | Mechanism | Guards against |
+|-------|-----------|----------------|
+| Single write | temp file + `rename()` (POSIX-atomic) | torn/corrupt files on crash |
+| One process | FIFO queue inside `MemoryStore` | same-instance async races (touch vs archive, parallel stores) |
+| Many processes | `<root>/.remembra.lock` (`O_EXCL` create) | MCP server vs `remembra maintain` CLI vs a second session |
+
+Lock rules:
+
+- acquired around every mutating operation (store/update/archive/revive/
+  touch/forget/import) **including its read**, so read-modify-write cycles are
+  whole;
+- **stale steal**: a lock whose pid is dead (or older than
+  `REMEMBRA_LOCK_STALE_MS`, default 10 s) is removed; the `O_EXCL` re-create
+  decides the winner;
+- **timeout**: waiting longer than `REMEMBRA_LOCK_TIMEOUT_MS` (default 5 s)
+  fails with the typed `LOCK_TIMEOUT` error (HTTP 423);
+- released in a `finally`, verified by pid before unlinking.
+
+Reads (`get`/`all`) don't lock — atomic rename means they always see a
+consistent file.
+
+## Crash recovery (audit Phase 3: "journal")
+
+Atomic `rename()` already guarantees no half-written memory files, so instead
+of a write-ahead log (which would itself need journaling) Remembra runs a
+one-time **recovery pass** on first store access per process:
+
+1. delete orphaned `*.tmp` files (crash between write and rename);
+2. reconcile ids found in **both** active and archived trees (crash between
+   archive/revive's write and unlink, audit finding #19) — newest `updatedAt`
+   wins, ties go to the archived copy.
+
+Anything it fixes is logged:
+`Remembra: crash recovery — removed N orphaned temp file(s), reconciled N interrupted move(s)`.
+
+## Error classification (audit Phase 2)
+
+All actionable failures are `RemembraError` with a stable `code`
+(`src/errors.ts`): `INVALID_INPUT`, `SNAPSHOT_INVALID`, `SCOPE_ESCAPES_ROOT`,
+`NOT_FOUND`, `CONFLICT`, `LOCK_TIMEOUT`, `IO_ERROR`, `LLM_ERROR`.
+
+- **HTTP** maps codes → statuses (400/404/409/423/500/502) and returns
+  `{ error, code }` bodies;
+- **MCP tools** return `[CODE] message` text with `isError: true`;
+- raw filesystem failures are wrapped as `IO_ERROR`; Zod failures crossing a
+  service boundary become `INVALID_INPUT`/`SNAPSHOT_INVALID` with a field
+  summary.
+
+## Schema versioning
+
+Every memory file carries `version: <n>` in frontmatter (`SCHEMA_VERSION` in
+`types.ts`). Files without the field (v1–v3.1) parse as v1. To change the
+format: bump the constant, add a migration branch in `parse()`, and cover it
+with a fixture test.

package/docs/clients.md

@@ -92,6 +92,9 @@ REMEMBRA_API_KEY="your-secret" remembra --http
 | `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_LOCK_TIMEOUT_MS` | `5000` | Max wait for the cross-process storage lock |
+| `REMEMBRA_LOCK_STALE_MS` | `10000` | Age after which a lock with a dead/unknown pid is stolen |
+| `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

@@ -52,6 +52,9 @@ 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) |
+| **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 |
 
@@ -70,8 +73,9 @@ remembra --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 (there is **no built-in
-      backup yet** — the files are the only copy)
+- [ ] `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
 
@@ -82,8 +86,9 @@ remembra --http
 - **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 protect against crashes,
-  not interleaving).
-- **No built-in backup/export** — planned; until then, back up `REMEMBRA_HOME`
-  with your normal file backup (it's plain files, `rsync`/git all work).
+- **Single-writer assumption per store, now cross-process safe** — mutations
+  take an advisory lockfile (`O_EXCL`, stale-steal, typed `LOCK_TIMEOUT`), so
+  an MCP server, the `remembra maintain` CLI, and a session digest can run
+  against one store concurrently on one machine. Network filesystems with
+  unreliable `O_EXCL` semantics are untested; `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.1.0",
+  "version": "3.3.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": {