openclaw-engram 0.5.0 → 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# openclaw-engram
+
+OpenClaw plugin that connects agents to an [engram](https://github.com/thebtf/engram) persistent memory server for long-term context retention.
+
+## Prerequisites
+
+- OpenClaw gateway installed and running
+- Engram server running and reachable (default port `37777`)
+- An API token configured on the engram server
+
+## Installation
+
+### Fresh install
+
+1. **Temporarily remove the memory slot if configured** (avoids circular validation during install):
+
+   ```bash
+   # If plugins.slots.memory is currently set to "engram", clear it first:
+   openclaw config set plugins.slots.memory ""
+   ```
+
+2. **Install the plugin:**
+
+   ```bash
+   openclaw plugins install openclaw-engram
+   ```
+
+   This runs `npm pack` and extracts the plugin into `~/.openclaw/extensions/engram/`.
+
+3. **Configure the engram server connection:**
+
+   ```bash
+   openclaw config set plugins.entries.engram.config.url http://your-engram-server:37777
+   openclaw config set plugins.entries.engram.config.token your-api-token
+   ```
+
+4. **Assign as the memory backend:**
+
+   ```bash
+   openclaw config set plugins.slots.memory engram
+   ```
+
+5. **Restart the gateway:**
+
+   ```bash
+   openclaw gateway restart
+   ```
+
+### Updating
+
+```bash
+openclaw plugins install openclaw-engram
+openclaw gateway restart
+```
+
+### Note on package naming
+
+The npm package is `openclaw-engram` but the plugin ID is `engram`.
+OpenClaw may show a cosmetic warning about ID mismatch — this is harmless.
+The plugin registers and operates correctly under the `engram` ID.
+
+## Configuration
+
+All fields are set under `plugins.entries.engram.config`:
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `url` | string | `http://localhost:37777` | Engram server base URL |
+| `token` | string | *(required)* | Bearer token for API authentication |
+| `project` | string | *(auto-detected)* | Project scope override; defaults to workspace identity |
+| `contextLimit` | number | `10` | Maximum observations injected per prompt turn |
+| `sessionContextLimit` | number | `20` | Maximum observations injected at session start |
+| `tokenBudget` | number | `2000` | Token budget for context injection (~4 chars/token) |
+| `timeoutMs` | number | `5000` | Per-request HTTP timeout in milliseconds |
+| `autoExtract` | boolean | `true` | Auto-extract observations on compaction and session end |
+| `workspaceDir` | string | `~/.openclaw/workspace/` | Workspace path for `/migrate` when called from channel context (Telegram, Discord) |
+| `logLevel` | string | `warn` | Log verbosity: `debug`, `info`, `warn`, `error` |
+
+## What it provides
+
+### Hooks
+
+The plugin hooks into the agent lifecycle automatically — no configuration needed:
+
+| Hook | Effect |
+|---|---|
+| `session_start` | Injects up to `sessionContextLimit` relevant observations into system context |
+| `before_prompt_build` | Injects up to `contextLimit` observations relevant to the current turn |
+| `after_tool_call` | Forwards tool events to engram for self-learning |
+| `before_compaction` | Backfills conversation transcript into engram before context is compacted |
+| `session_end` | Final transcript backfill when the session closes |
+
+### Agent tools
+
+Available to the agent during a session:
+
+| Tool | Description |
+|---|---|
+| `engram_search` | Semantic search across all stored observations |
+| `memory_search` | Alias for `engram_search` (memory-core compatible name) |
+| `engram_remember` | Store a new observation with structured metadata |
+| `memory_store` | Alias for `engram_remember` |
+| `engram_decisions` | Retrieve past architectural decisions by query |
+| `memory_get` | Retrieve a specific observation by ID |
+| `memory_forget` | Delete an observation by ID |
+| `memory_migrate` | Import local `MEMORY.md` / `memory/**/*.md` files into engram |
+
+### Slash commands
+
+| Command | Description |
+|---|---|
+| `/memory` | Show memory status and search |
+| `/remember <text>` | Store a memory immediately |
+| `/migrate [--dry-run] [--force] [path]` | Import local memory files into engram |
+
+### CLI
+
+```bash
+openclaw memory status              # Show server health and version
+openclaw memory search <query>      # Search engram memory
+openclaw memory store <text>        # Store a memory
+openclaw memory migrate             # Import local memory files
+openclaw memory migrate --dry-run   # Preview without importing
+openclaw memory migrate --force     # Re-import already migrated files
+```
+
+## Troubleshooting
+
+**"plugin not found: engram" during install**
+
+Circular dependency: OpenClaw tries to load the memory plugin before it is installed.
+Fix: clear `plugins.slots.memory` first (step 1 of Installation), install, then re-set the slot.
+
+**"plugin id mismatch" warning**
+
+The npm package name (`openclaw-engram`) differs from the plugin ID (`engram`).
+This is cosmetic — the plugin loads and works correctly. No action needed.
+
+**Plugin loads but no memory is injected into prompts**
+
+1. Verify the server is reachable: `openclaw memory status`
+2. Check `url` and `token` are set correctly
+3. Increase `logLevel` to `debug` and restart the gateway to see injection details
+4. Confirm `plugins.slots.memory` is set to `engram`
+
+**Context injection is slow or times out**
+
+Increase `timeoutMs` (default 5000 ms). Engram failures are non-blocking — if the server is unreachable the agent continues without memory context.
+
+## Development
+
+Requirements: Node.js >=18, TypeScript >=5.
+
+```bash
+cd plugin/openclaw-engram
+npm install
+npm run build       # compile TypeScript → dist/
+npm run typecheck   # type-check without emitting
+```
+
+The compiled output in `dist/` is what OpenClaw loads. Re-run `npm run build` after any source change and restart the gateway.

package/dist/context/formatter.js

@@ -146,7 +146,7 @@ function applyTokenBudget(observations, tokenBudget) {
     return { budgeted, trimmedCount: observations.length - budgeted.length };
 }
 function renderXml(groups) {
-    let out = '<relevant-memory>\n';
+    let out = '<engram-context>\n';
     out += '# Relevant Knowledge From Previous Sessions\n';
     out +=
         'IMPORTANT: Use this information to answer the question directly. Do NOT explore the codebase if the answer is here.\n\n';
@@ -187,7 +187,7 @@ function renderXml(groups) {
         'REMINDER: Before modifying any file mentioned above, call `engram_search(query="path")` to check for additional context. ';
     out +=
         'Before architectural decisions, call `engram_decisions(query="...")`. These engram tools are available and MUST be used.\n';
-    out += '</relevant-memory>\n';
+    out += '</engram-context>\n';
     return out;
 }
 //# sourceMappingURL=formatter.js.map

package/dist/context/formatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/context/formatter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/context/formatter.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAuDH,sCAgDC;AAnFD,MAAM,YAAY,GAA6D;IAC7E,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE;IACxC,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,2BAA2B,EAAE;IACvD,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,gBAAgB,EAAE;IAC3C,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE;CAC7C,CAAC;AAeF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAC3B,YAA2B,EAC3B,UAA4B,EAAE;IAE9B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAEhD,wBAAwB;IACxB,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,CAC9B,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,YAAY,CAC3D,CAAC;IAEF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC3D,CAAC;IAED,wCAAwC;IACxC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;IAEnF,mBAAmB;IACnB,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAErC,8BAA8B;IAC9B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,OAAO,GAAkB;QAC7B,GAAG,OAAO,CAAC,SAAS;QACpB,GAAG,OAAO,CAAC,QAAQ;QACnB,GAAG,OAAO,CAAC,OAAO;QAClB,GAAG,OAAO,CAAC,OAAO;KACnB,CAAC;IAEF,kBAAkB;IAClB,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAE1E,uBAAuB;IACvB,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,EAAE,GAAG,CAAC;YAAE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,yBAAyB;IACzB,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAEvC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,QAAQ,CAAC,KAAK,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,YAA2B;IAC/C,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACtE,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;YACxE,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;gBAAE,SAAS;YACpD,MAAM,YAAY,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACpE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YAClD,IAAI,KAAK,GAAG,CAAC,IAAI,YAAY,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;gBAC5C,KAAK,GAAG,IAAI,CAAC;gBACb,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,YAA2B;IAC9C,MAAM,MAAM,GAAwB;QAClC,SAAS,EAAE,EAAE;QACb,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,EAAE;KACZ,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YACrB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,WAAW,EAAE,CAAC;YAChD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;aAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YAC9C,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CACvB,YAA2B,EAC3B,WAAmB;IAEnB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;QAC/C,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACpC,IAAI,UAAU,GAAG,MAAM,GAAG,WAAW;YAAE,SAAS;QAChD,UAAU,IAAI,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC3E,CAAC;AAED,SAAS,SAAS,CAAC,MAA2B;IAC5C,IAAI,GAAG,GAAG,oBAAoB,CAAC;IAC/B,GAAG,IAAI,+CAA+C,CAAC;IACvD,GAAG;QACD,yHAAyH,CAAC;IAE5H,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,YAAY,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAEtC,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC;QACxB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC5D,MAAM,KAAK,GACT,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,gBAAgB,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,MAAM,QAAQ,GACZ,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;YAE7E,GAAG,IAAI,MAAM,GAAG,MAAM,OAAO,KAAK,KAAK,GAAG,QAAQ,GAAG,QAAQ,IAAI,CAAC;YAElE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,GAAG,IAAI,cAAc,CAAC;gBACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;gBACrB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;wBAC5C,QAAQ,GAAG,IAAI,CAAC;wBAChB,GAAG,IAAI,KAAK,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;oBAClC,CAAC;gBACH,CAAC;gBACD,IAAI,QAAQ;oBAAE,GAAG,IAAI,IAAI,CAAC;YAC5B,CAAC;YAED,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC3C,IAAI,SAAS,KAAK,EAAE;gBAAE,GAAG,IAAI,GAAG,SAAS,MAAM,CAAC;YAEhD,GAAG,EAAE,CAAC;QACR,CAAC;IACH,CAAC;IAED,GAAG,IAAI,SAAS,CAAC;IACjB,GAAG;QACD,2HAA2H,CAAC;IAC9H,GAAG;QACD,4HAA4H,CAAC;IAC/H,GAAG,IAAI,qBAAqB,CAAC;IAC7B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/context/tiers.d.ts

@@ -0,0 +1,26 @@
+export type ContextTier = 'FULL' | 'TARGETED' | 'MINIMAL' | 'NONE';
+export interface TierConfig {
+    /** How often to do a FULL search (every N turns). Default: 8. */
+    fullSearchInterval: number;
+    /** How often to do a MINIMAL search if no other trigger. Default: 4. */
+    minimalInterval: number;
+    /** Maximum prompt length (chars) to be classified as NONE. Default: 30. */
+    shortPromptMaxChars: number;
+}
+export declare const DEFAULT_TIER_CONFIG: TierConfig;
+export interface TierResult {
+    tier: ContextTier;
+    tokenBudget: number;
+    reason: string;
+}
+export declare class TurnTracker {
+    private turnCount;
+    private lastPrompt;
+    private readonly config;
+    constructor(config?: Partial<TierConfig>);
+    /** Classify the current turn and return the appropriate tier. */
+    classify(prompt: string): TierResult;
+    /** Reset tracker (e.g., on new session). */
+    reset(): void;
+}
+//# sourceMappingURL=tiers.d.ts.map

package/dist/context/tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/context/tiers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAEnE,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,mBAAmB,EAAE,UAIjC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AA4DD,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAExB,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC;IAIxC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IA+CpC,4CAA4C;IAC5C,KAAK,IAAI,IAAI;CAId"}

package/dist/context/tiers.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnTracker = exports.DEFAULT_TIER_CONFIG = void 0;
+exports.DEFAULT_TIER_CONFIG = {
+    fullSearchInterval: 8,
+    minimalInterval: 4,
+    shortPromptMaxChars: 30,
+};
+const TOKEN_BUDGETS = {
+    FULL: 2000,
+    TARGETED: 1000,
+    MINIMAL: 500,
+    NONE: 0,
+};
+const RECALL_PHRASES = [
+    'remember',
+    'recall',
+    'what do you know about',
+    'prior decision',
+    'previous session',
+    'what was decided',
+    'engram',
+    'memory',
+];
+const STOP_WORDS = new Set([
+    'the', 'this', 'that', 'with', 'from', 'have', 'been',
+    'will', 'would', 'could', 'should', 'about', 'into',
+    'what', 'when', 'where', 'which', 'there', 'their',
+    'also', 'just', 'more', 'some', 'than', 'them', 'then',
+    'very', 'your', 'make', 'like', 'does', 'each', 'only',
+    'need', 'want', 'please', 'can', 'are', 'for', 'and',
+    'but', 'not', 'you', 'all', 'any', 'her', 'was', 'one',
+    'our', 'out', 'has', 'had', 'how', 'its', 'may', 'new',
+    'now', 'old', 'see', 'way', 'who', 'did', 'get', 'let',
+    'say', 'she', 'too', 'use',
+]);
+function extractSignificantWords(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((w) => w.length > 3 && !STOP_WORDS.has(w)));
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    const intersection = new Set([...a].filter((w) => b.has(w)));
+    const union = new Set([...a, ...b]);
+    return union.size === 0 ? 1 : intersection.size / union.size;
+}
+function isTopicShift(current, previous) {
+    if (!previous)
+        return false;
+    const currentWords = extractSignificantWords(current);
+    const previousWords = extractSignificantWords(previous);
+    return jaccardSimilarity(currentWords, previousWords) < 0.3;
+}
+function makeTier(tier, reason) {
+    return { tier, tokenBudget: TOKEN_BUDGETS[tier], reason };
+}
+class TurnTracker {
+    turnCount = 0;
+    lastPrompt = '';
+    config;
+    constructor(config) {
+        this.config = { ...exports.DEFAULT_TIER_CONFIG, ...config };
+    }
+    /** Classify the current turn and return the appropriate tier. */
+    classify(prompt) {
+        this.turnCount++;
+        const lowerPrompt = prompt.toLowerCase();
+        const hasRecallPhrase = RECALL_PHRASES.some((phrase) => lowerPrompt.includes(phrase));
+        // Rule 1: First turn always gets full context.
+        if (this.turnCount === 1) {
+            this.lastPrompt = prompt;
+            return makeTier('FULL', 'first turn');
+        }
+        // Rule 2: Explicit recall phrases trigger FULL.
+        if (hasRecallPhrase) {
+            this.lastPrompt = prompt;
+            return makeTier('FULL', 'explicit recall');
+        }
+        // Rule 3: Short prompts without a question mark → NONE.
+        if (prompt.length <= this.config.shortPromptMaxChars && !prompt.includes('?')) {
+            this.lastPrompt = prompt;
+            return makeTier('NONE', 'short response');
+        }
+        // Rule 4: Periodic FULL.
+        if (this.turnCount % this.config.fullSearchInterval === 0) {
+            this.lastPrompt = prompt;
+            return makeTier('FULL', 'periodic full');
+        }
+        // Rule 5: Periodic MINIMAL.
+        if (this.turnCount % this.config.minimalInterval === 0) {
+            this.lastPrompt = prompt;
+            return makeTier('MINIMAL', 'periodic minimal');
+        }
+        // Rule 6: Topic shift → TARGETED.
+        if (isTopicShift(prompt, this.lastPrompt)) {
+            this.lastPrompt = prompt;
+            return makeTier('TARGETED', 'topic shift');
+        }
+        // Default: no trigger.
+        this.lastPrompt = prompt;
+        return makeTier('NONE', 'no trigger');
+    }
+    /** Reset tracker (e.g., on new session). */
+    reset() {
+        this.turnCount = 0;
+        this.lastPrompt = '';
+    }
+}
+exports.TurnTracker = TurnTracker;
+//# sourceMappingURL=tiers.js.map

package/dist/context/tiers.js.map

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

package/dist/hooks/after-tool-call.d.ts

@@ -7,13 +7,14 @@
  */
 import type { EngramRestClient } from '../client.js';
 import type { PluginConfig } from '../config.js';
-import type { AfterToolCallEvent } from '../types/openclaw.js';
+import type { AfterToolCallEvent, PluginHookContext } from '../types/openclaw.js';
 /**
  * Handle the after_tool_call hook.
  *
  * @param event  - The after_tool_call event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
  * @param client - Shared engram REST client.
  * @param config - Resolved plugin config.
  */
-export declare function handleAfterToolCall(event: AfterToolCallEvent, client: EngramRestClient, config: PluginConfig): void;
+export declare function handleAfterToolCall(event: AfterToolCallEvent, ctx: PluginHookContext, client: EngramRestClient, config: PluginConfig): void;
 //# sourceMappingURL=after-tool-call.d.ts.map

package/dist/hooks/after-tool-call.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"after-tool-call.d.ts","sourceRoot":"","sources":["../../src/hooks/after-tool-call.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,GACnB,IAAI,CA0BN"}
+{"version":3,"file":"after-tool-call.d.ts","sourceRoot":"","sources":["../../src/hooks/after-tool-call.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKlF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,GACnB,IAAI,CA0BN"}

package/dist/hooks/after-tool-call.js

@@ -15,16 +15,17 @@ const TOOL_RESULT_MAX_CHARS = 500;
  * Handle the after_tool_call hook.
  *
  * @param event  - The after_tool_call event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
  * @param client - Shared engram REST client.
  * @param config - Resolved plugin config.
  */
-function handleAfterToolCall(event, client, config) {
+function handleAfterToolCall(event, ctx, client, config) {
     if (!client.isAvailable())
         return;
     if (!config.autoExtract)
         return;
-    const agentId = event.agentId ?? '';
-    const identity = (0, identity_js_1.resolveIdentity)(agentId, event.workspaceDir);
+    const agentId = ctx.agentId ?? '';
+    const identity = (0, identity_js_1.resolveIdentity)(agentId, ctx.workspaceDir);
     const project = config.project ?? identity.projectId;
     let toolInput;
     let toolResult;

package/dist/hooks/after-tool-call.js.map

@@ -1 +1 @@
-{"version":3,"file":"after-tool-call.js","sourceRoot":"","sources":["../../src/hooks/after-tool-call.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAiBH,kDA8BC;AA3CD,gDAAiD;AAGjD,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;;;GAMG;AACH,SAAgB,mBAAmB,CACjC,KAAyB,EACzB,MAAwB,EACxB,MAAoB;IAEpB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;QAAE,OAAO;IAClC,IAAI,CAAC,MAAM,CAAC,WAAW;QAAE,OAAO;IAEhC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAA,6BAAe,EAAC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC;IAErD,IAAI,SAAiB,CAAC;IACtB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAClF,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,qBAAqB,CAAC,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,kBAAkB,CAAC;QAC/B,UAAU,GAAG,kBAAkB,CAAC;IAClC,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,CAAC,WAAW,CAAC;QACtB,UAAU,EAAE,OAAO;QACnB,OAAO;QACP,SAAS,EAAE,KAAK,CAAC,QAAQ,IAAI,SAAS;QACtC,UAAU,EAAE,SAAS;QACrB,WAAW,EAAE,UAAU;KACxB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAmC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa,EAAE,QAAgB;IAC/C,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"after-tool-call.js","sourceRoot":"","sources":["../../src/hooks/after-tool-call.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAkBH,kDA+BC;AA7CD,gDAAiD;AAGjD,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;;;;GAOG;AACH,SAAgB,mBAAmB,CACjC,KAAyB,EACzB,GAAsB,EACtB,MAAwB,EACxB,MAAoB;IAEpB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;QAAE,OAAO;IAClC,IAAI,CAAC,MAAM,CAAC,WAAW;QAAE,OAAO;IAEhC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAA,6BAAe,EAAC,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC;IAErD,IAAI,SAAiB,CAAC;IACtB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAClF,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,qBAAqB,CAAC,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,kBAAkB,CAAC;QAC/B,UAAU,GAAG,kBAAkB,CAAC;IAClC,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,CAAC,WAAW,CAAC;QACtB,UAAU,EAAE,OAAO;QACnB,OAAO;QACP,SAAS,EAAE,KAAK,CAAC,QAAQ,IAAI,SAAS;QACtC,UAAU,EAAE,SAAS;QACrB,WAAW,EAAE,UAAU;KACxB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAmC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAa,EAAE,QAAgB;IAC/C,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/hooks/before-agent-start.d.ts

@@ -0,0 +1,23 @@
+/**
+ * before_agent_start hook — fetches static session context from engram and
+ * injects it as appendSystemContext so it is available for the entire session.
+ *
+ * This hook replaces the context-injection logic that was previously in
+ * session_start. The SDK passes agent identity via ctx (not event), so all
+ * identity resolution happens here via the ctx parameter.
+ */
+import type { EngramRestClient } from '../client.js';
+import type { PluginConfig } from '../config.js';
+import type { BeforeAgentStartEvent, BeforeAgentStartResult, PluginHookContext, PluginLogger } from '../types/openclaw.js';
+/**
+ * Handle the before_agent_start hook.
+ *
+ * @param event  - The before_agent_start event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
+ * @param client - Shared engram REST client.
+ * @param config - Resolved plugin config.
+ * @param logger - Optional logger (falls back to console).
+ * @returns      Append-system-context result, or void if nothing to inject.
+ */
+export declare function handleBeforeAgentStart(event: BeforeAgentStartEvent, ctx: PluginHookContext, client: EngramRestClient, config: PluginConfig, logger?: PluginLogger): Promise<BeforeAgentStartResult | void>;
+//# sourceMappingURL=before-agent-start.d.ts.map

package/dist/hooks/before-agent-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-agent-start.d.ts","sourceRoot":"","sources":["../../src/hooks/before-agent-start.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,EACb,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CA6DxC"}

package/dist/hooks/before-agent-start.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * before_agent_start hook — fetches static session context from engram and
+ * injects it as appendSystemContext so it is available for the entire session.
+ *
+ * This hook replaces the context-injection logic that was previously in
+ * session_start. The SDK passes agent identity via ctx (not event), so all
+ * identity resolution happens here via the ctx parameter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleBeforeAgentStart = handleBeforeAgentStart;
+const identity_js_1 = require("../identity.js");
+const formatter_js_1 = require("../context/formatter.js");
+/**
+ * Handle the before_agent_start hook.
+ *
+ * @param event  - The before_agent_start event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
+ * @param client - Shared engram REST client.
+ * @param config - Resolved plugin config.
+ * @param logger - Optional logger (falls back to console).
+ * @returns      Append-system-context result, or void if nothing to inject.
+ */
+async function handleBeforeAgentStart(event, ctx, client, config, logger) {
+    try {
+        if (!client.isAvailable())
+            return;
+        const agentId = ctx.agentId ?? '';
+        const identity = (0, identity_js_1.resolveIdentity)(agentId, ctx.workspaceDir);
+        const project = config.project ?? identity.projectId;
+        const response = await client.getContextInject(agentId, ctx.workspaceDir);
+        if (!response || !Array.isArray(response.observations) || response.observations.length === 0) {
+            return;
+        }
+        const { context, injectedIds, trimmedCount } = (0, formatter_js_1.formatContext)(response.observations, { tokenBudget: config.tokenBudget });
+        if (trimmedCount > 0) {
+            (logger ?? console).warn(`[engram] before-agent-start: trimmed ${trimmedCount} observations to fit token budget`);
+        }
+        if (!context)
+            return;
+        // Mark observations as injected (fire-and-forget)
+        if (injectedIds.length > 0 && response.sessionId) {
+            void client.markInjected(response.sessionId, injectedIds);
+        }
+        // Initialize session tracking (fire-and-forget)
+        const claudeSessionId = ctx.sessionId ?? agentId;
+        if (!claudeSessionId) {
+            (logger ?? console).warn('[engram] before-agent-start: no sessionId or agentId available — skipping session init');
+        }
+        else {
+            void client.initSession({
+                claudeSessionId,
+                project,
+                prompt: event.initialPrompt,
+            });
+        }
+        (logger ?? console).warn(`[engram] before-agent-start: injected ${injectedIds.length} observations for project ${project}`);
+        // Build static instructions + dynamic session context
+        const staticInstructions = buildStaticInstructions(project);
+        const fullContext = staticInstructions + '\n\n' + context;
+        return { appendSystemContext: fullContext };
+    }
+    catch (err) {
+        (logger ?? console).error('[engram] hook error:', err);
+    }
+}
+/**
+ * Build cacheable static instructions injected once per session.
+ * These describe available engram capabilities to the agent.
+ */
+function buildStaticInstructions(project) {
+    return [
+        '# Engram Persistent Memory',
+        '',
+        'You have access to persistent memory via engram. Available tools:',
+        '- `engram_search` — search prior observations, decisions, and patterns',
+        '- `engram_remember` — store new observations for future sessions',
+        '- `engram_decisions` — query architectural decisions',
+        '',
+        `Memory is scoped to project "${project}". Use \`engram_remember\` to store important insights, decisions, and discoveries.`,
+    ].join('\n');
+}
+//# sourceMappingURL=before-agent-start.js.map

package/dist/hooks/before-agent-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"before-agent-start.js","sourceRoot":"","sources":["../../src/hooks/before-agent-start.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAuBH,wDAmEC;AAtFD,gDAAiD;AACjD,0DAAwD;AAQxD;;;;;;;;;GASG;AACI,KAAK,UAAU,sBAAsB,CAC1C,KAA4B,EAC5B,GAAsB,EACtB,MAAwB,EACxB,MAAoB,EACpB,MAAqB;IAErB,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;YAAE,OAAO;QAElC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAA,6BAAe,EAAC,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC;QAErD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC5C,OAAO,EACP,GAAG,CAAC,YAAY,CACjB,CAAC;QAEF,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7F,OAAO;QACT,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,IAAA,4BAAa,EAC1D,QAAQ,CAAC,YAAY,EACrB,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CACpC,CAAC;QAEF,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,CACtB,wCAAwC,YAAY,mCAAmC,CACxF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,kDAAkD;QAClD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACjD,KAAK,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC5D,CAAC;QAED,gDAAgD;QAChD,MAAM,eAAe,GAAG,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC;QACjD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,CACtB,wFAAwF,CACzF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,WAAW,CAAC;gBACtB,eAAe;gBACf,OAAO;gBACP,MAAM,EAAE,KAAK,CAAC,aAAa;aAC5B,CAAC,CAAC;QACL,CAAC;QAED,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,CACtB,yCAAyC,WAAW,CAAC,MAAM,6BAA6B,OAAO,EAAE,CAClG,CAAC;QAEF,sDAAsD;QACtD,MAAM,kBAAkB,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,WAAW,GAAG,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;QAE1D,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAAC,OAAe;IAC9C,OAAO;QACL,4BAA4B;QAC5B,EAAE;QACF,mEAAmE;QACnE,wEAAwE;QACxE,kEAAkE;QAClE,sDAAsD;QACtD,EAAE;QACF,gCAAgC,OAAO,qFAAqF;KAC7H,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/hooks/before-compaction.d.ts

@@ -7,13 +7,14 @@
  */
 import type { EngramRestClient } from '../client.js';
 import type { PluginConfig } from '../config.js';
-import type { BeforeCompactionEvent, PluginLogger } from '../types/openclaw.js';
+import type { BeforeCompactionEvent, PluginHookContext, PluginLogger } from '../types/openclaw.js';
 /**
  * Handle the before_compaction hook.
  *
  * @param event  - The before_compaction event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
  * @param client - Shared engram REST client.
  * @param config - Resolved plugin config.
  */
-export declare function handleBeforeCompaction(event: BeforeCompactionEvent, client: EngramRestClient, config: PluginConfig, logger?: PluginLogger): void;
+export declare function handleBeforeCompaction(event: BeforeCompactionEvent, ctx: PluginHookContext, client: EngramRestClient, config: PluginConfig, logger?: PluginLogger): void;
 //# sourceMappingURL=before-compaction.d.ts.map

package/dist/hooks/before-compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"before-compaction.d.ts","sourceRoot":"","sources":["../../src/hooks/before-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOrG;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,YAAY,GACpB,IAAI,CA+BN"}
+{"version":3,"file":"before-compaction.d.ts","sourceRoot":"","sources":["../../src/hooks/before-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOxH;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,YAAY,GACpB,IAAI,CAgCN"}

package/dist/hooks/before-compaction.js

@@ -17,26 +17,28 @@ const CONTENT_MAX_CHARS = 6000;
  * Handle the before_compaction hook.
  *
  * @param event  - The before_compaction event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
  * @param client - Shared engram REST client.
  * @param config - Resolved plugin config.
  */
-function handleBeforeCompaction(event, client, config, logger) {
+function handleBeforeCompaction(event, ctx, client, config, logger) {
     try {
         if (!client.isAvailable())
             return;
         if (!config.autoExtract)
             return;
-        const agentId = event.agentId ?? '';
-        const identity = (0, identity_js_1.resolveIdentity)(agentId, event.workspaceDir);
+        const agentId = ctx.agentId ?? '';
+        const identity = (0, identity_js_1.resolveIdentity)(agentId, ctx.workspaceDir);
         const project = config.project ?? identity.projectId;
         const messages = Array.isArray(event.messages) ? event.messages : [];
         const recent = messages.slice(-MAX_MESSAGES);
         const content = serializeMessages(recent);
         if (!content)
             return;
-        const truncated = content.length > CONTENT_MAX_CHARS
-            ? content.slice(0, CONTENT_MAX_CHARS)
-            : content;
+        const stripped = stripEngramContext(content);
+        const truncated = stripped.length > CONTENT_MAX_CHARS
+            ? stripped.slice(0, CONTENT_MAX_CHARS)
+            : stripped;
         // Fire-and-forget — do not await
         void client.backfillSession({
             session_id: agentId,
@@ -57,4 +59,7 @@ function serializeMessages(messages) {
         .map((m) => `[${m.role}]: ${m.content}`)
         .join('\n\n');
 }
+function stripEngramContext(text) {
+    return text.replace(/<engram-context>[\s\S]*?<\/engram-context>/g, '');
+}
 //# sourceMappingURL=before-compaction.js.map

package/dist/hooks/before-compaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"before-compaction.js","sourceRoot":"","sources":["../../src/hooks/before-compaction.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAmBH,wDAoCC;AAnDD,gDAAiD;AAGjD,kEAAkE;AAClE,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,KAA4B,EAC5B,MAAwB,EACxB,MAAoB,EACpB,MAAqB;IAErB,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;YAAE,OAAO;QAClC,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO;QAEhC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAA,6BAAe,EAAC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;QAC9D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC;QAErD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,iBAAiB;YAClD,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC;YACrC,CAAC,CAAC,OAAO,CAAC;QAEZ,iCAAiC;QACjC,KAAK,MAAM,CAAC,eAAe,CAAC;YAC1B,UAAU,EAAE,OAAO;YACnB,OAAO;YACP,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;QAEH,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,CACtB,0CAA0C,MAAM,CAAC,MAAM,mCAAmC,OAAO,GAAG,CACrG,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,iBAAiB,CAAC,QAA+B;IACxD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;SACvC,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"before-compaction.js","sourceRoot":"","sources":["../../src/hooks/before-compaction.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAoBH,wDAsCC;AAtDD,gDAAiD;AAGjD,kEAAkE;AAClE,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CACpC,KAA4B,EAC5B,GAAsB,EACtB,MAAwB,EACxB,MAAoB,EACpB,MAAqB;IAErB,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE;YAAE,OAAO;QAClC,IAAI,CAAC,MAAM,CAAC,WAAW;YAAE,OAAO;QAEhC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAA,6BAAe,EAAC,OAAO,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC;QAErD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,iBAAiB;YACnD,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC;YACtC,CAAC,CAAC,QAAQ,CAAC;QAEb,iCAAiC;QACjC,KAAK,MAAM,CAAC,eAAe,CAAC;YAC1B,UAAU,EAAE,OAAO;YACnB,OAAO;YACP,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;QAEH,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,CACtB,0CAA0C,MAAM,CAAC,MAAM,mCAAmC,OAAO,GAAG,CACrG,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,iBAAiB,CAAC,QAA+B;IACxD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;SACvC,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,OAAO,CAAC,6CAA6C,EAAE,EAAE,CAAC,CAAC;AACzE,CAAC"}

package/dist/hooks/before-prompt-build.d.ts

@@ -7,14 +7,15 @@
  */
 import type { EngramRestClient } from '../client.js';
 import type { PluginConfig } from '../config.js';
-import type { BeforePromptBuildEvent, PromptBuildResult, PluginLogger } from '../types/openclaw.js';
+import type { BeforePromptBuildEvent, PromptBuildResult, PluginHookContext, PluginLogger } from '../types/openclaw.js';
 /**
  * Handle the before_prompt_build hook.
  *
  * @param event  - The before_prompt_build event from OpenClaw.
+ * @param ctx    - The hook context containing agent identity fields.
  * @param client - Shared engram REST client.
  * @param config - Resolved plugin config.
  * @returns      Context to prepend, or void if nothing to inject.
  */
-export declare function handleBeforePromptBuild(event: BeforePromptBuildEvent, client: EngramRestClient, config: PluginConfig, logger?: PluginLogger): Promise<PromptBuildResult | void>;
+export declare function handleBeforePromptBuild(event: BeforePromptBuildEvent, ctx: PluginHookContext, client: EngramRestClient, config: PluginConfig, logger?: PluginLogger): Promise<PromptBuildResult | void>;
 //# sourceMappingURL=before-prompt-build.d.ts.map