Tools
Um Injector
By Local-first long-term memory injection plugin for OpenClaw agent reliability
Install
openclaw plugins install .README
# OpenClaw UM Injector
[](./LICENSE)
[](./package.json)
[](./openclaw.plugin.json)
Silent long-term memory injection for OpenClaw agent sessions.
OpenClaw UM Injector is a small, local-first plugin that helps an OpenClaw main agent remember critical operational facts between chats. It retrieves a short memory block from local long-term memory, merges in pinned safety facts, and injects the result before prompt build so the agent does not need the user to repeat the same setup details every session.
<p align="center">
<img src="docs/assets/architecture.svg" alt="OpenClaw UM Injector architecture" width="780">
</p>
## Why this exists
Stateless agent sessions often forget important working context:
- browser and CDP lane rules
- upload workarounds for web application forms
- active operational promises
- tool routing rules
- budget or workflow constraints
- task-specific safety reminders
This plugin keeps those facts close to the agent while staying local-first, capped, and fail-safe.
## What it does
- Injects up to 3 relevant facts into the main-agent system prompt.
- Uses local `memories.db` first and pinned facts as a safety net.
- Works offline for the basic path.
- Falls back safely from hybrid search to text search to pinned facts only.
- Writes plugin health so fallback hooks can detect whether injection is alive.
- Ships smoke-test, install, prefetch, and hook-enforcement scripts.
## Demo output
The smoke test below runs without a database and demonstrates the pinned-facts fallback path.
<p align="center">
<img src="docs/assets/smoke-test-output.svg" alt="Smoke test terminal output" width="780">
</p>
```bash
node ./scripts/test-injection.js "job application"
```
Expected behavior:
- `source` is `no-db` when no memory database is present.
- `retrievalTier` falls back to `tier3`.
- the output still includes a bounded `[MEMORY CONTEXT]` block.
## Quick start
### 1. Clone the repo
```bash
git clone https://github.com/Abbabk/openclaw-um-injector.git
cd openclaw-um-injector
```
### 2. Install the plugin into OpenClaw
```bash
openclaw plugins install .
```
For local development, use a linked install:
```bash
openclaw plugins install . --link
```
### 3. Seed config and pinned facts
```bash
node ./scripts/install-host.js
```
This backs up `openclaw.json`, ensures the plugin is allowed and enabled, and seeds `pinned-facts.json` if it does not already exist.
### 4. Restart the gateway
```bash
openclaw gateway restart
```
### 5. Verify
```bash
openclaw plugins inspect openclaw-um-injector --json
node ./scripts/test-injection.js "job application"
node ./scripts/enforce-hooks.js --mode preflight
```
## How it works
```text
User message
-> before_prompt_build hook
-> query normalization
-> fresh prefetch if available
-> local memory search
-> pinned facts merge
-> dedupe and cap
-> hidden [MEMORY CONTEXT] block
-> plugin health file
```
Deep dive: [docs/HOW_IT_WORKS.md](./docs/HOW_IT_WORKS.md)
Security model: [docs/SECURITY_MODEL.md](./docs/SECURITY_MODEL.md)
Maintainer workflows: [docs/MAINTAINER_WORKFLOWS.md](./docs/MAINTAINER_WORKFLOWS.md)
## Install model
The plugin is self-contained and lives in the OpenClaw extensions directory after install.
Core files:
- `index.ts` - plugin entry, registers `before_prompt_build`
- `lib/memory-injection.cjs` - retrieval engine, tiering, prompt block assembly, plugin health
- `data/pinned-facts.json` - critical always-on or trigger-matched facts
Companion scripts:
- `scripts/pre-message-hook.js` - optional richer prefetch helper
- `scripts/test-injection.js` - smoke test for what would be injected
- `scripts/enforce-hooks.js` - optional audit for HOOK 1/2/3 compliance
## Default behavior
| Setting | Default |
| --- | --- |
| `scope` | `main` |
| `queryChars` | `200` |
| `maxFacts` | `3` |
| `maxInjectionChars` | `400` |
| `pluginHealthTtlMs` | `300000` |
| `useUltraMemory` | `false` |
The default path is local-first and offline-capable.
## Verification targets
- `node ./scripts/test-injection.js "job application"` should surface pinned facts when no database is available.
- `openclaw plugins inspect openclaw-um-injector --json` should show the plugin as loaded with `before_prompt_build` available.
- Gateway logs should show `um-injector: injected ...` when memory context is added.
- `node ./scripts/enforce-hooks.js --mode audit --latest` should append violations when required hooks are missing.
## Use with Codex
This project is a good fit for Codex-assisted maintenance because the risky parts are reviewable and testable:
- prompt-injection hardening
- memory retrieval refactors
- hook safety review
- test generation
- release notes
- documentation cleanup
- issue triage and reproduction steps
See [docs/MAINTAINER_WORKFLOWS.md](./docs/MAINTAINER_WORKFLOWS.md).
## Suggested release paths
- Easiest for users: clone repo, then run `openclaw plugins install .`
- Better long-term DX: publish to npm and let users run `openclaw plugins install <package-name>`
- Optional later: publish a release archive so users can install from `.zip` or `.tgz`
## License
MIT
tools
Comments
Sign in to leave a comment