Episodic Memory

Name: Episodic Memory
Rating: 3.5 (1 reviews)
Author: dave-melillo

By dave-melillo 👁 8 views ▲ 0 votes

Production-ready episodic memory plugin for OpenClaw agents

GitHub

Install

pip install -e

README

# openclaw-episodic-memory

> Production-ready episodic memory plugin for OpenClaw agents

## Overview

OpenClaw Episodic Memory System is a plugin-based episodic memory layer that enables agents to recall specific past experiences, decisions, and context with high fidelity. Unlike semantic memory (facts/preferences) or working memory (current session), episodic memory captures the "what happened when" narrative of each agent's work history.

## Features

- ✅ **Auto-Capture:** Episodes automatically created from `log-work.sh` calls
- ✅ **Fast Search:** <1s temporal/metadata queries, <3s semantic queries
- ✅ **Multi-Modal Queries:** Search by date, agent, outcome, tags, or semantic content
- ✅ **Cross-Agent Discovery:** All agents can search each other's episodes
- ✅ **Human-Readable Storage:** Episodes stored as YAML files
- ✅ **CLI Tools:** List, search, show, export commands
- ✅ **Memory Tool Integration:** Extends `memory_recall` for episodic queries

## Quick Start

### Installation

```bash
git clone https://github.com/dave-melillo/openclaw-episodic-memory.git
cd openclaw-episodic-memory
pip install -e .
./scripts/post-install.sh
```

### Usage

```bash
# List recent episodes
openclaw episodes list --agent professorx --after "7 days ago"

# Search semantically
openclaw episodes search "PRD writing"

# Show full episode
openclaw episodes show <episode-id>

# Export to CSV
openclaw episodes export --format csv --output episodes.csv
```

## Architecture

```
Episodes Storage:
~/.openclaw/episodes/
  ├── professorx/
  │   ├── <uuid>.yaml
  │   └── <uuid>.yaml
  └── wolverine/
      └── <uuid>.yaml

Index Database:
~/.openclaw/episodes.db (SQLite)
```

## Status

🚧 **Stage:** PRD Complete - Implementation In Progress

**PRD:** [PRD-20260328-001](https://trello.com/c/nHtJe4Fp)
**Estimated PRs:** 8 (PR 1: Setup in progress)

## Documentation

- [PRD](./docs/PRD-20260328-001.md) - Product Requirements Document
- [Architecture](./docs/architecture.md) - System design (coming soon)
- [API Reference](./docs/api.md) - CLI and Python API (coming soon)

## Contributing

This project is actively developed by Professor X as part of the X-Men AI agent team.

## License

MIT

---

*Created by X-Men Pipeline*
*Project Owner: Professor X 🧠*

tools