Session Retrieval

Native OpenClaw plugin for forensic raw session retrieval from OpenClaw transcripts.

Version: 1.0.0

What it does

This plugin registers a native OpenClaw tool named session_retrieval.

Supported actions:

• route
• search
• list-sessions
• media

The plugin wrapper (index.js) handles:

• tool registration
• selective before_prompt_build retrieval guidance for recall-sensitive turns
• parameter validation
• path resolution
• agent resolution
• Python subprocess execution
• structured result shaping

The Python scripts in scripts/ handle the forensic backend work.

Directory layout

session-retrieval/
├── index.js
├── install.sh
├── openclaw.plugin.json
├── package.json
├── SKILL.md
├── LICENSE
├── README.md
└── scripts/
    ├── _session_utils.py
    ├── media_scan.py
    ├── route.py
    └── session_search.py

Requirements

• OpenClaw with plugin support
• Python 3 available as python3, or configure another binary in plugin config

Install locally

Option A: one-command install via curl

Set the AGENT_USER to your agent username on the system

AGENT_USER=openclaw
curl -fsSL https://raw.githubusercontent.com/catx0rr/session-retrieval/main/install.sh | bash

This downloads the repo, places it at:

/home/${AGENT_USER}/.openclaw/extensions/session-retrieval

Then runs the plugin installer automatically.

You can inspect it afterward with:

openclaw plugins inspect session-retrieval

Option B: clone the repo, then install from the plugin directory

AGENT_USER=openclaw
git clone https://github.com/catx0rr/session-retrieval.git /home/${AGENT_USER}/.openclaw/extensions/session-retrieval
cd /home/${AGENT_USER}/.openclaw/extensions/session-retrieval
openclaw plugins install .

Option C: manual copy into extensions root

Copy the folder into the OpenClaw extensions directory, then reload or restart the gateway.

Example target:

~/.openclaw/extensions/session-retrieval

After that, reload the gateway and inspect the plugin:

openclaw plugins inspect session-retrieval

Example tool calls

Search transcripts

session_retrieval(action="search", keyword="reflex-guard")

Route to likely sessions

session_retrieval(action="route", context="group", groupId="1203...@g.us")

List sessions

session_retrieval(action="list-sessions", channel="whatsapp", dateFrom="2026-04-01")

Scan inbound media

session_retrieval(action="media", keyword="agentchronicles", fileType="pdf")

Why this plugin exists

Compared with a skill-only workflow, a native plugin is better for execution because:

• the runtime can call the tool directly
• parameters are schema-validated
• execution is deterministic
• path handling is portable
• results come back in a structured shape
• the model does not need to reconstruct script usage from memory

Notes

• SKILL.md may still be useful as documentation or retrieval doctrine, but it is not required for the plugin to load or register the tool.
• The plugin also ships a selective before_prompt_build hook that nudges the model toward lighter retrieval first, and toward forensic/session retrieval only when exact evidence is needed.
• That guidance is plugin-configurable via enablePromptGuidance: true|false and defaults to true.
• If a deployment wants the tool without prompt injection, OpenClaw can disable plugin prompt mutation with plugins.entries.<id>.hooks.allowPromptInjection: false.
• openclaw.plugin.json and package.json are the files that make this a native OpenClaw plugin.