Tools

OME

Name: OME
Rating: 3.5 (1 reviews)
Author: DEEP-IOS

By DEEP-IOS 👁 13 views ▲ 0 votes

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.

GitHub

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: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js 24+](https://img.shields.io/badge/node-24+-blue.svg)](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