@engramx/openclaw 0.1.0-rc.2

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 EngramX contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,277 @@
+# EngramX + OpenClaw Integration
+
+Hybrid memory plugin for [OpenClaw](https://github.com/openclaw/openclaw): local SQLite for fast search, [EngramX](https://engramx.ai) canister as the persistent source of truth, and periodic database backup to the canister for disaster recovery. Auto-detects active databases (SQLite, QMD, LanceDB) from `openclaw.json`.
+
+## Architecture
+
+The canister exposes two storage systems: **Files** (memory markdown + session JSONL) and **Blobs** (SQLite backup chunks). Sessions are stored as JSONL files under `sessions/{agentId}/{key}.jsonl` — no separate session API.
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                          OpenClaw Gateway                           │
+│                                                                     │
+│  memory_search / memory_get ─────► Local SQLite (sqlite-vec + FTS5) │
+│       (sub-100ms hybrid search)         ▲                           │
+│                                         │ file watch + re-index     │
+│  engram_append_memory ──► EngramX ──────┤                           │
+│       (source of truth)   canister      │ sync to local disk        │
+│                              │          ▼                           │
+│                              │     memory/*.md (local files)        │
+│                              │     sessions/{agentId}/*.jsonl       │
+│                              │                                      │
+│  periodic backup ────────────┤                                      │
+│       (every 6h)             │     detected DBs ───────► EngramX    │
+│                              │     (SQLite/QMD/LanceDB, 1.9 MiB chunks)│
+│                              │                                      │
+│  engram_wallet_balance ──────┘     Direct canister access (wallet)  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Why hybrid?
+
+| Concern | Local SQLite | EngramX Canister |
+|---|---|---|
+| **Search latency** | 50-200ms (vector + FTS5) | Not available (search removed) |
+| **Write latency** | <1ms | 2-5s (ICP consensus) |
+| **Persistence** | Lost if machine dies | Survives anything (on-chain) |
+| **Vector search** | sqlite-vec cosine distance | Not available |
+| **Disaster recovery** | None | Backup API (500 MiB max) |
+
+The SQLite database is a **derived cache** — it's rebuilt from markdown files + an embedding provider. EngramX stores the source markdown. If you lose your machine, pull the files from EngramX and the SQLite index rebuilds automatically.
+
+## What it provides
+
+### Search tools (local SQLite — fast)
+
+| Tool | Description |
+|---|---|
+| `memory_search` | Hybrid vector + FTS5 search across memory (sub-100ms) |
+| `memory_get` | Read a local memory file by path |
+
+These are identical to OpenClaw's built-in `memory-core` tools. Search never hits the canister.
+
+### Engram tools (canister — persistent)
+
+| Tool | Description |
+|---|---|
+| `engram_append_memory` | Append to a memory file (writes to canister + local disk). Owner-protected paths are read-only for operators. |
+| `engram_read_memory` | Read a file directly from the canister |
+| `engram_list_memory` | List all files in the canister (includes session JSONL files) |
+| `engram_wallet_balance` | Check engram wallet balance |
+
+> No `engram_transfer` / write / delete / rollback tools — operators are append-only
+> and have no owner-level fund control by design.
+
+Sessions are stored as regular files (`sessions/{agentId}/{key}.jsonl`) and are visible via `engram_list_memory`. There is no separate session tool.
+
+### Background services
+
+- **Memory sync** — pulls markdown files from canister to local disk on startup and periodically (default: every 60 min). Local writes are pushed back to the canister.
+- **Database backup** — auto-detects active databases from `openclaw.json` and uploads snapshots periodically (default: every 6 hours). Uses `sqlite3 .backup` for consistent SQLite snapshots, `tar.gz` for directory-based backends (QMD, LanceDB). SHA-256 deduplication skips unchanged databases.
+- **Session sync** — serializes conversation transcripts to JSONL and appends them to `sessions/{agentId}/{key}.jsonl` in the canister after each conversation. Always enabled.
+
+### CLI commands
+
+```
+openclaw memory search <query>    # Search local SQLite (fast)
+openclaw engram status            # Canister status
+openclaw engram sync              # Pull/push memory files now
+openclaw engram backup            # Backup all detected databases now
+openclaw engram restore           # List available backups (grouped by type)
+openclaw engram files             # List canister memory files (includes sessions)
+```
+
+---
+
+## Option 1: Hosted (engramx.ai)
+
+Use this when your engram is running on the IC mainnet via [engramx.ai](https://engramx.ai).
+
+### 1. Create an engram
+
+Sign up at [engramx.ai](https://engramx.ai) and create an engram. Note your **canister ID**.
+
+### 2. Create an operator invite
+
+In the engramx.ai dashboard, go to Access > Operators and click "Create Invite".
+
+### 3. Pair and install
+
+```bash
+# First host — push local memory to engram
+npx @engramx/client pair <INVITE_CODE> --engram <CANISTER_ID> --openclaw
+
+# Replacement host — restore from engram
+npx @engramx/client pair <INVITE_CODE> --engram <CANISTER_ID> --openclaw --recover
+```
+
+This generates a session key, registers the operator, installs the plugin, configures `openclaw.json`, and either migrates local files or restores database backups. A local checkpoint is saved first — run `engramx rollback` to undo.
+
+### 4. Verify
+
+```bash
+openclaw engram status
+```
+
+### Manual configuration
+
+If you need to customize the plugin config, edit `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "slots": {
+      "memory": "memory-engramx"
+    },
+    "entries": {
+      "memory-engramx": {
+        "canisterId": "xxxxx-xxxxx-xxxxx-xxxxx-xxx",
+        // Memory file sync: canister <-> local disk
+        "sync": {
+          "onStartup": true,        // pull files when OpenClaw starts
+          "intervalMinutes": 60,     // sync every hour
+          "pushOnWrite": true        // write to both canister and local
+        },
+        // Database backup: auto-detects SQLite/QMD/LanceDB
+        "backup": {
+          "enabled": true,
+          "intervalMinutes": 360     // backup every 6 hours
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Option 2: Local Development
+
+Use this to develop and test against a local ICP replica before `@engramx/client` is on npm.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 22.12
+- [pnpm](https://pnpm.io/) 10.x
+- [ICP CLI](https://github.com/nicoll-douglas/icp-cli) (`icp`)
+- The [engramx](https://github.com/vhew/engramx) repo cloned locally
+- The [openclaw](https://github.com/openclaw/openclaw) (OpenClaw) repo cloned locally
+
+### 1. Start EngramX locally
+
+```bash
+cd /path/to/engramx
+pnpm local:start
+pnpm local:create-engram    # note the ENGRAM_ID
+```
+
+### 2. Configure protected paths (optional)
+
+Designate which file paths are owner-protected (read-only for operators):
+
+```bash
+icp canister call <ENGRAM_ID> setProtectedPaths '(vec { "SOUL.md"; "USER.md"; "AGENTS.md" })' -e local
+```
+
+### 3. Build and link `@engramx/client`
+
+```bash
+cd /path/to/engramx/packages/client
+pnpm install && pnpm build
+pnpm link --global
+```
+
+### 4. Set up the plugin in OpenClaw
+
+```bash
+cp -r /path/to/engramx/integrations/openclaw /path/to/openclaw/extensions/memory-engramx
+cd /path/to/openclaw/extensions/memory-engramx
+pnpm install
+pnpm link --global @engramx/client
+```
+
+### 5. Create an operator and pair
+
+```bash
+# Create an invite (as the engram owner)
+icp canister call <ENGRAM_ID> createOperatorInvite \
+  '("openclaw-dev", record { canRead = true; canWrite = true; canTransfer = false; dailySpendingLimitE8s = opt 0 })' \
+  -e local
+
+# Pair and configure OpenClaw in one step
+npx @engramx/client pair <INVITE_CODE> --engram <ENGRAM_ID> --openclaw --host http://localhost:4943
+```
+
+The `--openclaw` flag installs the plugin config in `~/.openclaw/openclaw.json` automatically.
+
+### 6. Run OpenClaw
+
+```bash
+cd /path/to/openclaw
+pnpm gateway:watch
+```
+
+### 7. Verify
+
+```bash
+openclaw engram status
+openclaw engram sync
+openclaw engram backup    # triggers backup of all detected databases
+```
+
+### Resetting local state
+
+```bash
+cd /path/to/engramx
+pnpm local:reset --nuke && pnpm local:start
+# Repeat steps 1 and 5 to recreate engram + operator
+```
+
+---
+
+## Configuration Reference
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `canisterId` | string | *required* | Engram canister ID (also reads `ENGRAM_CANISTER_ID` env) |
+| `sessionKeyPath` | string | `~/.engramx/session.key` | Path to Ed25519 operator session key |
+| `host` | string | `https://ic0.app` | ICP replica host |
+| `memoryDir` | string | `memory` | Local directory for memory markdown files |
+| `sync.onStartup` | boolean | `true` | Pull memory files from canister on startup |
+| `sync.intervalMinutes` | number | `60` | Periodic sync interval (0 = disabled) |
+| `sync.pushOnWrite` | boolean | `true` | Write to both canister and local disk |
+| `backup.enabled` | boolean | `true` | Enable periodic database backup (auto-detects SQLite/QMD/LanceDB) |
+| `backup.intervalMinutes` | number | `360` | Backup interval in minutes (minimum 30) |
+| `backup.dbLabel` | string | auto | Label for backup snapshots |
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `ENGRAM_CANISTER_ID` | Fallback canister ID if not set in config |
+| `ENGRAM_SESSION_KEY_PATH` | Override session key path |
+| `OPENCLAW_STATE_DIR` | Override `.openclaw` directory location |
+
+## Disaster Recovery
+
+If you lose your machine:
+
+```bash
+# On a clean machine — create a new operator invite from the dashboard, then:
+npx @engramx/client pair <INVITE_CODE> --engram <CANISTER_ID> --openclaw --recover
+```
+
+This registers a new operator, installs the plugin, restores the latest database backups (SQLite, QMD, LanceDB — whichever were detected), and saves a checkpoint. Memory files sync automatically on next OpenClaw startup.
+
+A local checkpoint is saved before any changes. Run `engramx rollback` to undo.
+
+The only thing that needs regeneration is the embedding vectors, which are computed locally by the embedding provider (OpenAI, Gemini, etc.). The embedding cache in the database backup avoids re-computing embeddings for unchanged content.
+
+### Manual recovery
+
+If you prefer fine-grained control:
+
+1. Set up OpenClaw + this plugin on a new machine
+2. Run `openclaw engram sync` — pulls all memory files from the canister
+3. Run `openclaw engram restore` — lists available backups grouped by database type
+4. Download and restore via the client SDK's backup API

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+export type EngramXPluginConfig = {
+    canisterId: string;
+    sessionKeyPath?: string;
+    host?: string;
+    memoryDir?: string;
+    sync: {
+        onStartup: boolean;
+        intervalMinutes: number;
+        pushOnWrite: boolean;
+    };
+    backup: {
+        enabled: boolean;
+        intervalMinutes: number;
+        dbLabel?: string;
+    };
+    git: {
+        enabled: boolean;
+        pushOnSync: boolean;
+        pushOnStop: boolean;
+    };
+};
+export declare function sha256File(filePath: string): string;
+export declare const engramxConfigSchema: {
+    parse(value: unknown): EngramXPluginConfig;
+};

package/dist/config.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+const ALLOWED_KEYS = ['canisterId', 'sessionKeyPath', 'host', 'memoryDir', 'sync', 'backup', 'git'];
+const SYNC_KEYS = ['onStartup', 'intervalMinutes', 'pushOnWrite'];
+const BACKUP_KEYS = ['enabled', 'intervalMinutes', 'dbLabel'];
+const GIT_KEYS = ['enabled', 'pushOnSync', 'pushOnStop'];
+const ALLOWED_ENV_VARS = new Set([
+    'HOME',
+    'USER',
+    'ENGRAM_CANISTER_ID',
+    'ENGRAM_SESSION_KEY_PATH',
+    'ENGRAMX_SESSION_KEY_PATH',
+    'VAULT_CANISTER_ID',
+    'VAULT_SESSION_KEY_PATH',
+    'ENGRAM_HOST',
+    'ENGRAM_OFFLINE_QUEUE_PATH',
+    'VAULT_OFFLINE_QUEUE_PATH',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+]);
+function resolveEnvVars(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+        if (!ALLOWED_ENV_VARS.has(envVar)) {
+            throw new Error(`Environment variable ${envVar} is not in the allowlist`);
+        }
+        const envValue = process.env[envVar];
+        if (!envValue) {
+            throw new Error(`Environment variable ${envVar} is not set`);
+        }
+        return envValue;
+    });
+}
+function assertAllowedKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+        throw new Error(`memory-engramx ${label}: unknown keys: ${unknown.join(', ')}`);
+    }
+}
+export function sha256File(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+export const engramxConfigSchema = {
+    parse(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('memory-engramx: config object required');
+        }
+        const cfg = value;
+        assertAllowedKeys(cfg, ALLOWED_KEYS, 'config');
+        const canisterId = typeof cfg.canisterId === 'string'
+            ? resolveEnvVars(cfg.canisterId)
+            : process.env['ENGRAM_CANISTER_ID'];
+        if (!canisterId) {
+            throw new Error('memory-engramx: canisterId is required (config or ENGRAM_CANISTER_ID env)');
+        }
+        // Parse sync options
+        let sync = { onStartup: true, intervalMinutes: 60, pushOnWrite: true };
+        if (cfg.sync && typeof cfg.sync === 'object' && !Array.isArray(cfg.sync)) {
+            const s = cfg.sync;
+            assertAllowedKeys(s, SYNC_KEYS, 'sync');
+            sync = {
+                onStartup: s.onStartup !== false,
+                intervalMinutes: typeof s.intervalMinutes === 'number' ? Math.max(0, s.intervalMinutes) : 60,
+                pushOnWrite: s.pushOnWrite !== false,
+            };
+        }
+        // Parse backup options
+        let backup = { enabled: true, intervalMinutes: 360, dbLabel: undefined };
+        if (cfg.backup && typeof cfg.backup === 'object' && !Array.isArray(cfg.backup)) {
+            const b = cfg.backup;
+            assertAllowedKeys(b, BACKUP_KEYS, 'backup');
+            backup = {
+                enabled: b.enabled !== false,
+                intervalMinutes: typeof b.intervalMinutes === 'number' ? Math.max(30, b.intervalMinutes) : 360,
+                dbLabel: typeof b.dbLabel === 'string' ? b.dbLabel : undefined,
+            };
+        }
+        // Parse git options
+        let git = { enabled: false, pushOnSync: false, pushOnStop: true };
+        if (cfg.git && typeof cfg.git === 'object' && !Array.isArray(cfg.git)) {
+            const g = cfg.git;
+            assertAllowedKeys(g, GIT_KEYS, 'git');
+            git = {
+                enabled: g.enabled === true,
+                pushOnSync: g.pushOnSync === true,
+                pushOnStop: g.pushOnStop !== false,
+            };
+        }
+        return {
+            canisterId,
+            sessionKeyPath: typeof cfg.sessionKeyPath === 'string' ? cfg.sessionKeyPath : undefined,
+            host: typeof cfg.host === 'string' ? cfg.host : undefined,
+            memoryDir: typeof cfg.memoryDir === 'string' ? cfg.memoryDir : undefined,
+            sync,
+            backup,
+            git,
+        };
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * OpenClaw Memory Plugin: EngramX (Hybrid Architecture)
+ *
+ * This plugin uses a hybrid approach:
+ *
+ *   EngramX canister  = source of truth for markdown memory files
+ *   Local SQLite       = performance cache for search (vector + FTS5)
+ *   EngramX backup API = disaster recovery for the SQLite database
+ *
+ * How it works:
+ *   1. Local SQLite search (memory_search / memory_get) — delegated to
+ *      OpenClaw's built-in memory-core runtime, which uses sqlite-vec
+ *      and FTS5 for sub-100ms hybrid search. Never queries the canister.
+ *
+ *   2. Memory file sync — pulls markdown files from the engram canister
+ *      to the local memory/ directory on startup and periodically. Local
+ *      file changes are pushed back to the canister. The existing SQLite
+ *      indexer watches these files and re-chunks/embeds automatically.
+ *
+ *   3. Database backup — auto-detects active databases (SQLite, QMD,
+ *      LanceDB) from openclaw.json and periodically uploads snapshots
+ *      to the engram canister's backup API for disaster recovery.
+ *
+ *   4. Session sync — serializes conversation transcripts to JSONL files
+ *      stored in the canister under sessions/{agentId}/{key}.jsonl.
+ *
+ *   5. Supplementary engram_* tools — direct canister access for wallet,
+ *      audit log, and cross-machine memory retrieval.
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+declare const memoryEngramXPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    kind: "memory";
+    configSchema: {
+        parse(value: unknown): import("./config.js").EngramXPluginConfig;
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default memoryEngramXPlugin;