Tools
OME
By Every AI agent session starts fresh. Previous context is lost after resets, and users must repeat themselves. OME solves this by providing a zero-dependency persistent memory layer as an OpenClaw plugin, enabling agents to remember, learn, and continue across sessions.
Configuration Example
{
"plugins": {
"entries": {
"ome": {
"enabled": true,
"config": {
"dbPath": "~/.openclaw/ome/ome.db",
"maxPrependChars": 4000,
"maxMsgChars": 500,
"maxRecentMsgs": 3,
"maxRecentTools": 5,
"logLevel": "info"
}
}
}
}
}README
# OME — OpenClaw Memory Engine
[中文文档](README_CN.md)
**Persistent Memory Plugin for AI Agents**
[](LICENSE)
[](https://nodejs.org/)
Every AI agent session starts fresh. Previous context is lost after resets, and users must repeat themselves. OME solves this by providing a zero-dependency persistent memory layer as an OpenClaw plugin, enabling agents to remember, learn, and continue across sessions.
## Features
- **Cross-Session Persistence** — Survive `/new` resets with automatic checkpoint saving
- **Dual-Track Checkpoints** — Mechanical snapshots (always available) + LLM summaries (when available)
- **Per-Agent Isolation** — Each agent maintains its own private memory space
- **5-Level Memory Hierarchy** — D0 (themes) → D1 (gist) → D2 (outline) → D5 (exchanges) → D6 (raw)
- **4-Level Scope System** — Global, task, agent, and session scopes
- **Automatic Context Injection** — Previous session context restored on new sessions
- **Zero Dependencies** — Uses only Node.js 24+ built-in modules (`node:sqlite`)
- **SQLite WAL Storage** — Concurrent-safe, 1-5ms write latency
- **Configurable** — All parameters user-overridable, no hardcoded values
## Requirements
- Node.js >= 24.0.0 (uses built-in `node:sqlite`)
- OpenClaw >= 2026.2.0 (peer dependency)
## Installation
### Option 1: Copy to Extensions
```bash
# Create the extension directory
mkdir -p ~/.openclaw/extensions/ome
# Copy plugin source and config
cp -r src/ ~/.openclaw/extensions/ome/src/
cp -r config/ ~/.openclaw/extensions/ome/config/
# Enable the plugin in openclaw.json
cat <<'EOF' >> ~/.openclaw/openclaw.json
{
"plugins": {
"entries": {
"ome": {
"enabled": true
}
}
}
}
EOF
```
### Option 2: Git Clone
```bash
# Clone the repository
git clone https://github.com/user/ome.git ~/.openclaw/extensions/ome
# Or symlink from your dev directory
ln -s /path/to/ome ~/.openclaw/extensions/ome
```
After either approach, restart the OpenClaw Gateway.
## Configuration
OME uses a layered configuration system. Default values are built-in and can be overridden via `~/.openclaw/openclaw.json`:
```json
{
"plugins": {
"entries": {
"ome": {
"enabled": true,
"config": {
"dbPath": "~/.openclaw/ome/ome.db",
"maxPrependChars": 4000,
"maxMsgChars": 500,
"maxRecentMsgs": 3,
"maxRecentTools": 5,
"logLevel": "info"
}
}
}
}
}
```
| Parameter | Default | Description |
|-----------|---------|-------------|
| `dbPath` | `~/.openclaw/ome/ome.db` | Path to the SQLite database file |
| `maxPrependChars` | `4000` | Character budget for injected context |
| `maxMsgChars` | `500` | Max characters per message in checkpoints |
| `maxRecentMsgs` | `3` | Number of recent conversation turns to keep |
| `maxRecentTools` | `5` | Number of recent tool calls to keep |
| `maxModifiedFiles` | `20` | Number of modified files tracked |
| `logLevel` | `"info"` | Log verbosity: `debug`, `info`, `warn`, `error` |
## Architecture
```
┌─────────────────────────────────────────────┐
│ OpenClaw Gateway │
└──────────────────┬──────────────────────────┘
│
┌─────────────┼─────────────┐
│ │ │
┌────┴───┐ ┌────┴───┐ ┌────┴───┐
│ Main │ │Agent-A │ │Agent-B │
└────┬───┘ └────┬───┘ └────┬───┘
│ │ │
└─────────────┼─────────────┘
│
┌──────────┴──────────┐
│ OME Engine │
├─────────────────────┤
│ before_agent_start │ → Inject context
│ agent_end │ → Save checkpoint
│ after_tool_call │ → Track tool calls
│ before_reset │ → Pre-reset save
│ gateway_stop │ → Flush & close
└──────────┬──────────┘
│
┌──────────┴──────────┐
│ SQLite (WAL) │
│ ~/.openclaw/ome/ │
└─────────────────────┘
```
Each agent connects to the shared OME Engine, which persists all memory and checkpoints into a single SQLite database using WAL mode for concurrent safety.
## How It Works
### Checkpoint Lifecycle
| Hook | Trigger | Action |
|------|---------|--------|
| `before_agent_start` | New session detected | Inject previous session context via `prependContext` |
| `agent_end` | Each agent run completes | Save dual-track checkpoint + write D6 raw memory |
| `after_tool_call` | File-modifying tool calls | Track tool calls; checkpoint on file modifications |
| `before_reset` | `/new` or session reset | Save final checkpoint + write D5 session summary |
| `gateway_stop` | Gateway shutdown | Flush all active agent states, close database |
### Memory Layers
| Layer | Content | Size | Retention |
|-------|---------|------|-----------|
| D0 | Theme tags | ~50 tokens | Permanent |
| D1 | One-line gist | ~200 tokens | Permanent |
| D2 | Structured outline | ~500 tokens | Permanent |
| D5 | Exchange summary | ~3000 tokens | 7 days |
| D6 | Raw transcript | Unlimited | 7 days |
Consolidation path: `D6 → D5 → D2 → D1 → D0` (asynchronous, handled by the Consolidator in Phase 3).
### Scope Hierarchy
```
/global — Shared across all agents (user preferences, common knowledge)
/task/{task_id} — Shared within a collaboration task (goals, progress, findings)
/agent/{agent_id} — Private to a single agent
/session/{agent_id}/{sid} — Temporary, scoped to one session
```
Visibility: An agent sees `/global` + its participating `/task` scopes + its own `/agent` scope + the current `/session`.
### Context Injection Format
When a new session starts, OME injects the following via `prependContext`:
```
[OME Memory Restored — Last active: 15 minutes ago]
Goal: <current_goal>
Progress: <progress_summary>
Next step: <immediate_next>
Key findings: <key_findings>
Last user message: "<last_user_message>"
Recent conversation:
User: ...
Assistant: ...
Recent tool calls:
- edit({"filePath": "..."}) → Success
Modified files: src/index.js, src/config.js
```
If an LLM summary exists, it is used first. Otherwise, OME falls back to the mechanical checkpoint (recent messages, tool calls, modified files).
## Project Structure
```
ome/
├── config/
│ └── openclaw.plugin.json # Plugin manifest and config schema
├── docs/
│ ├── ARCHITECTURE.md # Detailed architecture documentation
│ ├── DEPLOY.md # Deployment guide
│ └── DESIGN.md # Full design specification
├── src/
│ ├── index.js # Plugin entry point and hook registration
│ ├── config.js # Configuration defaults and merge logic
│ ├── db.js # SQLite database module (schema, CRUD)
│ ├── hooks/
│ │ ├── before-agent-start.js # Context injection on new sessions
│ │ ├── agent-end.js # Checkpoint + D6 memory on agent completion
│ │ ├── after-tool-call.js # Tool call tracking + file-modify checkpoints
│ │ ├── before-reset.js # Final checkpoint + D5 summary before reset
│ │ └── gateway-stop.js # Graceful shutdown and database close
│ ├── services/
│ │ ├── agent-state-service.js # In-memory agent state management
│ │ ├── checkpoint-service.js # Dual-track checkpoint builder
│ │ └── context-service.js # prependContext builder
│ └── utils/
│ ├── agent-resolver.js # Agent ID resolution strategies
│ ├── logger.js # Configurable log wrapper
│ └── message-utils.js # Message parsing and text extraction
└── tests/
└── unit.test.js # Unit tests (Node.js built-in test runner)
```
## Testing
```bash
npm test
# or
node --test tests/unit.test.js
```
Tests use the Node.js built-in test runner (`node:test`) with zero external test dependencies.
## Roadmap
- **Phase 1**: Cross-session memory persistence — **Complete**
- **Phase 2**: Multi-agent shared memory (Task Memory + Memory Bus) — Designed
- **Phase 3**: Memory consolidation + daily reports — Planned
## References & Acknowledgments
This project's design was informed by research and ideas from:
- [Letta](https://github.com/letta-ai/letta) — Shared memory blocks, owner model, append-only patterns
- [CrewAI](https://github.com/crewAIInc/crewAI) — Scope hierarchy tree design
- [LangGraph](https://github.com/langchain-ai/langgraph) — Checkpointer vs Store dual-layer architecture
- CaveAgent (arXiv:2601.01569) — State externalization for persistent agents
- SPL (arXiv:2602.21257) — Token budget management strategies
## Disclaimer
This project is provided as-is, with no guarantees of continued maintenance, updates, or support. Use at your own discretion.
## License
MIT License. See [LICENSE](LICENSE) for details.
tools
Comments
Sign in to leave a comment