Total Recall

Note (April 2026): This project is currently on hold. I'm focusing on other work for the foreseeable future. The code works, the docs are accurate, and issues/PRs are welcome, but response times will be slower than usual. See #22 for details.

Autonomous memory for OpenClaw-style agents.

Total Recall v2.0 keeps the existing v1.x stack intact:

• Observer
• Reflector
• Session Recovery
• Reactive Watcher
• Dream Cycle

It also adds the Ambient Intelligence Engine (AIE): a configurable sensor and rumination pipeline that can watch external systems, think about what changed, maintain a preconscious buffer, and surface urgent items.

Prerequisites: python3, jq, curl, and PyYAML.

Install PyYAML with:

python3 -m pip install PyYAML
# or on Debian/Ubuntu:
sudo apt install python3-yaml

setup.sh will verify all dependencies are present before continuing.

Architecture

v1.x memory loop

Observer -> observations.md -> Reflector -> Dream Cycle -> session recovery / watcher

v2.0 Ambient Intelligence Engine

sensor-sweep
  -> enabled connectors emit events to memory/events/bus.jsonl
  -> rumination-engine reads new events and writes structured insights
  -> preconscious-select scores recent insights into memory/preconscious-buffer.md
  -> ambient-actions optionally enriches insights with read-only lookups
  -> emergency-surface pushes urgent alerts through configured channels
  -> buffer-inject sends the latest buffer back into the live session

The AIE flow is additive. None of the v1.x scripts are removed or replaced.

Quick Start

v1.x setup

git clone https://github.com/gavdalf/total-recall.git
cd total-recall
bash scripts/setup.sh

AIE setup

1. Review config/aie.yaml.
2. Set workspace if you do not want to use the repo root.
3. Enable only the connectors and notification channels you actually use.
4. Add credentials to ./.env or your shell environment.
5. Run a dry pass:

bash scripts/sensor-sweep.sh --dry-run
bash scripts/rumination-engine.sh --dry-run
bash scripts/preconscious-select.sh --dry-run
bash scripts/ambient-actions.sh --dry-run-actions

6. Schedule the AIE loop once the dry run looks correct:

*/15 * * * * OPENCLAW_WORKSPACE=/path/to/total-recall bash /path/to/total-recall/scripts/sensor-sweep.sh >> /path/to/total-recall/logs/sensor-sweep.log 2>&1
17,47 * * * * OPENCLAW_WORKSPACE=/path/to/total-recall bash /path/to/total-recall/scripts/preconscious-select.sh >> /path/to/total-recall/logs/rumination.log 2>&1
19,49 * * * * OPENCLAW_WORKSPACE=/path/to/total-recall bash /path/to/total-recall/scripts/emergency-surface.sh >> /path/to/total-recall/logs/emergency-surface.log 2>&1

Minimal first-run path:

• leave every connector disabled except filewatch
• keep notifications disabled
• set only the model IDs you want under models
• add the API key required by your chosen model provider

AIE Configuration

All new AIE behavior is controlled by config/aie.yaml.

Top-level sections