AMR - Active Memory Recall

AMR turns local conversation archives and memory files into searchable context for your OpenClaw agent, with a CLI for offline recall, a daemon that watches new session archives, and an optional dashboard for browsing sessions, live activity, annotations, and core memory files.

Quickstart: zero to green

From a clean machine to a green recall doctor:

# 1. Install the plugin (the unsafe flag is explained below)
openclaw plugins install @factshin/openclaw-recall --dangerously-force-unsafe-install
openclaw gateway restart

# 2. Install and start the daemon (macOS launchd; Linux: see Platform Compatibility)
recall daemon install
recall daemon start

# 3. Verify
recall doctor

That is the happy path. Read the security guidance below before exposing the dashboard to anything other than localhost.

What "green" looks like on first run

recall doctor ships with a few expected yellows on a fresh install. They are not failures:

• lancedb-plugin and lancedb-embeddings are yellow until the optional LanceDB plugin is installed and pointed at an embeddings store. AMR runs without it; semantic search is the feature you lose.
• promotion-log is yellow on first run because no sessions have been promoted yet. The first autopromote pass turns it green.
• ollama-running is yellow if you have not installed Ollama. AMR uses it for local LLM distillation when available; absent it, distillation falls back to deterministic extraction.

Everything else should be green. If something unexpected is yellow or red, check KNOWN-BUGS.md before filing an issue.

SECURITY: read this before configuring remote access

AMR runs an HTTP daemon that exposes:

• Read access to every conversation archive on this machine
• Read and write access to your agent's core memory files: MEMORY.md, IDENTITY.md, SOUL.md, AGENTS.md, HEARTBEAT.md, and .learnings/*
• A live view of the in-progress session

This is a privileged surface. Treat the daemon port the same way you would treat a database port.

Default posture: loopback only

By default the daemon binds to 127.0.0.1:7420. Only processes on the same machine can reach it. Other users on the same machine CAN reach the loopback port; AMR mitigates this with an auth token (see "Auth tokens" below).

Remote access: use Tailscale or another private mesh

If you want to reach the dashboard from another device:

• Use Tailscale, Wireguard, or another private mesh that already has clear trust rules.
• NEVER expose the daemon port to the public internet.
• NEVER set RECALL_HOST=0.0.0.0 unless you understand exactly what you are doing and have a private network protecting the port.

Auth tokens

A token at ~/.openclaw/workspace/.recall/auth-token (mode 0600) gates every /api/* route. Get yours with:

recall daemon token

Add it to the dashboard URL as ?token=<value>, or set the localStorage key amr-auth-token in your browser. Rotate with recall daemon token --rotate.

Disable the HTTP server entirely

If you only use the offline CLI (recall warm, recall sessions, etc.) you do not need the HTTP server. Disable it:

# At install time
recall daemon install --no-http

# Or in ~/.openclaw/workspace/.recall/daemon-config.json:
{ "http": { "enabled": false } }

The watcher and autopromote still run; the dashboard is unavailable.

What AMR persists

| Where | What | Permissions | |---|---|---| | ~/.openclaw/workspace/.recall/.recall | Warm-start cache (last N exchanges, redacted) | 0600 | | ~/.openclaw/workspace/.recall/.recall.history/ | Rotated cache snapshots | 0600 | | ~/.openclaw/workspace/.recall/.recall-promotion-log.jsonl | Append-only promotion records (redacted) | 0600 | | ~/.openclaw/memory/lancedb/ | Embeddings vault (redacted) | LanceDB plugin owns | | ~/.openclaw/wiki/main/entities/ | Wiki entity pages (redacted) | 0600 | | ~/.openclaw/logs/recall-daemon.log | Daemon stdout (paths sanitized to ~) | 0600 |

A redaction pass runs at every persistence boundary for known secret patterns (API keys, JWTs, SSH keys). To exclude an entire exchange from persistence, include the literal string [no-recall] anywhere in your message.

To audit your existing vault for unredacted secrets:

node ~/.openclaw/extensions/recall/scripts/scan-vault-for-secrets.js

Platform Compatibility

| Platform | Status | Notes | |---|---|---| | macOS (Apple Silicon + Intel) | Fully supported | Native launchd integration via recall daemon install. All M9 security guarantees in effect. | | Linux | CLI + manual daemon work today; systemd integration planned | recall daemon start runs the HTTP daemon in foreground or background. POSIX file modes, PID identity binding, and the redaction pipeline all work. recall daemon install is currently macOS-only; on Linux you can start the daemon manually or wrap it in a unit file you write yourself. Native systemd unit generation is on the roadmap. | | Windows | Experimental | CLI commands like recall warm, recall sessions, and recall search work because they are pure Node. The daemon lifecycle (daemon install / daemon start / daemon stop) is not supported: PID semantics, file modes, and the service-manager integration all assume Unix. We do not recommend Windows for production use yet. Investigation underway. |

If you are on Linux today and want to use AMR, the practical setup is:

recall daemon start --foreground

Run that in a terminal or under your shell's process supervisor. Everything else (auth tokens, redaction, the dashboard, the CLI) works the same as on macOS.

For roadmap items and planned platform work, see ROADMAP.md.

--dangerously-force-unsafe-install: why this is required

OpenClaw's plugin scanner flags AMR's legitimate child process call sites:

• cli.js:1143 - daemon spawn for recall daemon start
• lib/launchd.js around the launchctl load invocation for recall daemon install
• lib/launchd.js around the launchctl unload invocation for recall daemon uninstall

These calls use either spawn or execFileSync with argument arrays. There is no shell interpolation, no user input passed as a command, and no network egress from these calls. The flag is required because the scanner cannot distinguish a legitimate child process call from a shell injection target without manual verification.

You can read the exact call sites in the source. They will continue to require this flag until OpenClaw's scanner gains a manifest-level allowlist mechanism.

Install / configure / use

Install from OpenClaw

openclaw plugins install @factshin/openclaw-recall --dangerously-force-unsafe-install
openclaw gateway restart

Then install and start the daemon:

recall daemon install
recall daemon start
recall doctor

The dashboard listens on http://127.0.0.1:7420 by default.

Local development install

git clone https://github.com/FactShin/Active-Memory-Recall
cd Active-Memory-Recall
npm install
npm link
recall --help

Point AMR at your agent's session data:

export RECALL_WORKSPACE=/path/to/agent/workspace/.recall
export RECALL_LIVE_DIR=/path/to/agent/sessions
npm start

Or use a .env file:

RECALL_WORKSPACE=/path/to/agent/workspace/.recall
RECALL_LIVE_DIR=/path/to/agent/sessions
RECALL_PORT=7420
RECALL_HOST=127.0.0.1
RECALL_USER_NAME=You
RECALL_ASSISTANT_NAME=Assistant

Expected workspace layout:

RECALL_WORKSPACE/
  session-backups/          .jsonl session files
  recall-annotations.json   auto-created on first annotation
  memory/                   SOUL.md, AGENTS.md, MEMORY.md, and related files

What AMR does

Your OpenClaw agent already writes conversations down as .jsonl session files. AMR makes that history usable again.

The CLI can search prior sessions, read full transcripts, rebuild the warm-start cache, and promote durable facts or decisions into long-term memory stores. The daemon watches for rotated archives, rebuilds .recall, and can auto-promote when configured. The dashboard is the human side: session browser, full conversation viewer, memory file inspector, live session view, timeline, and annotations.

Short IDs work: recall read c0200c3f resolves to the full session file.

CLI reference

recall sessions                      # list recent sessions
recall sessions --limit 20 --json    # JSON output for piping
recall read <session-id>             # full transcript
recall read <id> --role user         # user messages only
recall read <id> --role assistant    # assistant messages only
recall search "query"                # full-text search across all sessions
recall search "query" --json         # structured JSON results
recall memory                        # print MEMORY.md
recall warm                          # rebuild and print the warm-start cache
recall promote --session <id>        # dry-run durable memory promotion
recall export <id> --format md       # export session as markdown
recall export <id> --out ./file.md   # write export to file
recall daemon status                 # check daemon status
recall daemon token                  # print the dashboard token

Environment variables

| Variable | Default | Description | |---|---|---| | RECALL_WORKSPACE | ~/.openclaw/workspace/.recall | Root for AMR cache, config, annotations, and session-backups | | RECALL_LIVE_DIR | ~/.recall/sessions | Active session directory for live view | | RECALL_PORT | 7420 | HTTP port | | RECALL_HOST | 127.0.0.1 | Bind address | | RECALL_HTTP_ENABLED | true | Set to false to disable the HTTP listener | | RECALL_USER_NAME | User | Display name for user role | | RECALL_ASSISTANT_NAME | Assistant | Display name for assistant role | | RECALL_URL | http://localhost:7420 | CLI server URL for HTTP-backed commands |

Dashboard

• Session browser: every conversation by date, searchable across content
• Full conversation viewer: role-colored messages and collapsible tool calls
• Memory file inspector: read and edit the whitelisted memory files
• Live session: active conversation, auto-refreshing every 30 seconds
• Timeline: session history laid out chronologically
• Annotations: notes, labels, and pinned messages

Keyboard shortcuts:

| Key | Action | |---|---| | J / K | Next / previous session | | N | Focus notes | | M | Memory Editor tab | | / | Focus search | | Escape | Close / blur |

Tech stack

• Backend: Node.js and Express
• Frontend: vanilla JS, HTML, and CSS
• Runtime dependency: express

Links

• Repository: https://github.com/FactShin/Active-Memory-Recall
• Issues: https://github.com/FactShin/Active-Memory-Recall/issues
• Known issues and workarounds: KNOWN-BUGS.md
• Roadmap: ROADMAP.md

License

MIT.