Skip to content
Back to search

total-recall

SkillWorks with Claude CodeGitHub

"Enable memory search on observations.md for cross-session recall"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gavdalf--total-recall/badge.svg)](/listings/gavdalf--total-recall)

HTML

<a href="/listings/gavdalf--total-recall"><img src="/api/listings/gavdalf--total-recall/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: total-recall
  3. description: "The only memory skill that watches on its own. No database. No vectors. No manual saves. Just an LLM observer that compresses your conversations into prioritised notes, consolidates when they grow, and recovers anything missed. Five layers of redundancy, zero maintenance. ~$0.00/month (using free-tier models). While other memory skills ask you to remember to remember, this one just pays attention."
  4. metadata:
  5. openclaw:
  6. emoji: "🧠"
  7. requires:
  8. bins: ["jq", "curl"]
  9. env:
  10. - key: OPENROUTER_API_KEY
  11. label: "OpenRouter API key (for LLM calls)"
  12. required: true
  13. config:
  14. memorySearch:
  15. description: "Enable memory search on observations.md for cross-session recall"
  16. ---
  17. # Total Recall — Autonomous Agent Memory
  18. **The only memory skill that watches on its own.**
  19. No database. No vectors. No manual saves. Just an LLM observer that compresses your conversations into prioritised notes, consolidates when they grow, and recovers anything missed. Five layers of redundancy, zero maintenance. ~$0.00/month (using free-tier models).
  20. While other memory skills ask you to remember to remember, this one just pays attention.
  21. ## Architecture
  22. ```
  23. Layer 1: Observer (cron, every 15-30 min)
  24. ↓ compresses recent messages → observations.md
  25. Layer 2: Reflector (auto-triggered when observations > 8000 words)
  26. ↓ consolidates, removes superseded info → 40-60% reduction
  27. Layer 3: Session Recovery (runs on every /new or /reset)
  28. ↓ catches any session the Observer missed
  29. Layer 4: Reactive Watcher (inotify daemon, Linux only)
  30. ↓ triggers Observer after 40+ new JSONL writes, 5-min cooldown
  31. Layer 5: Pre-compaction hook (memoryFlush)
  32. ↓ emergency capture before OpenClaw compacts context
  33. ```
  34. ## What It Does
  35. - **Observer** reads recent session transcripts (JSONL), sends them to an LLM, and appends compressed observations to `observations.md` with priority levels (high, medium, low)
  36. - **Reflector** kicks in when observations grow too large, consolidating related items and dropping stale low-priority entries
  37. - **Session Recovery** runs at session start, checks if the previous session was captured, and does an emergency observation if not
  38. - **Reactive Watcher** watches the session directory with inotify so high-activity periods get captured faster than the cron interval
  39. - **Pre-compaction hook** fires when OpenClaw is about to compact context, ensuring nothing is lost
  40. ## Quick Start
  41. ### 1. Install the skill
  42. ```bash
  43. clawdhub install total-recall
  44. ```
  45. ### 2. Set your API key
  46. Add to your `.env` or OpenClaw config:
  47. ```bash
  48. OPENROUTER_API_KEY=sk-or-v1-xxxxx
  49. ```
  50. ### 3. Run the setup script
  51. ```bash
  52. bash skills/total-recall/scripts/setup.sh
  53. ```
  54. This will:
  55. - Create the memory directory structure (`memory/`, `logs/`, backups)
  56. - On Linux with inotify + systemd: install the reactive watcher service
  57. - Print cron job and agent configuration instructions for you to add manually
  58. ### 4. Configure your agent to load observations
  59. Add to your agent's workspace context (e.g., `MEMORY.md` or system prompt):
  60. ```
  61. At session startup, read `memory/observations.md` for cross-session context.
  62. ```
  63. Or use OpenClaw's `memoryFlush.systemPrompt` to inject a startup instruction.
  64. ## Platform Support
  65. | Platform | Observer + Reflector + Recovery | Reactive Watcher |
  66. |----------|-------------------------------|-----------------|
  67. | Linux (Debian/Ubuntu/etc.) | Full support | With inotify-tools |
  68. | macOS | Full support | Not available (cron-only) |
  69. All core scripts use portable bash. `stat`, `date`, and `md5` commands are handled cross-platform via `_compat.sh`.
  70. ## Configuration
  71. All scripts read from environment variables with sensible defaults:
  72. | Variable | Default | Description |
  73. |----------|---------|-------------|
  74. | `OPENROUTER_API_KEY` | (required) | OpenRouter API key for LLM calls |
  75. | `MEMORY_DIR` | `$OPENCLAW_WORKSPACE/memory` | Where observations.md lives |
  76. | `SESSIONS_DIR` | `~/.openclaw/agents/main/sessions` | OpenClaw session transcripts |
  77. | `OBSERVER_MODEL` | `stepfun/step-3.5-flash:free` | Primary model for compression (free) |
  78. | `OBSERVER_FALLBACK_MODEL` | `nvidia/nemotron-3-nano-30b-a3b:free` | Fallback if primary fails (free) |
  79. | `OBSERVER_LOOKBACK_MIN` | `15` | Minutes to look back (daytime) |
  80. | `OBSERVER_MORNING_LOOKBACK_MIN` | `480` | Minutes to look back (before 8am) |
  81. | `OBSERVER_LINE_THRESHOLD` | `40` | Lines before reactive trigger (Linux) |
  82. | `OBSERVER_COOLDOWN_SECS` | `300` | Cooldown between reactive triggers (Linux) |
  83. | `REFLECTOR_WORD_THRESHOLD` | `8000` | Words before reflector runs |
  84. | `REFLECTOR_MODEL` | `nvidia/nemotron-3-super-120b-a12b:free` | Model for consolidating observations (free) |
  85. | `REFLECTOR_FALLBACK_MODEL` | `openrouter/hunter-alpha` | Fallback if reflector model fails (free) |
  86. | `OPENCLAW_WORKSPACE` | `~/your-workspace` | Workspace root |
  87. ## LLM Provider Configuration
  88. Total Recall uses any OpenAI-compatible chat completion API. Switch providers by setting environment variables:
  89. | Variable | Default | Description |
  90. |----------|---------|-------------|
  91. | `LLM_BASE_URL` | `https://openrouter.ai/api/v1` | API endpoint |
  92. | `LLM_API_KEY` | falls back to `OPENROUTER_API_KEY` | API key |
  93. | `LLM_MODEL` | `deepseek/deepseek-v3.2` | Model to use |
  94. ### Provider examples
  95. ```bash
  96. # OpenRouter (default)
  97. export OPENROUTER_API_KEY="your-key"
  98. # Ollama (local)
  99. export LLM_BASE_URL="http://localhost:11434/v1"
  100. export LLM_API_KEY="ollama"
  101. export LLM_MODEL="llama3.1:8b"
  102. # Groq
  103. export LLM_BASE_URL="https://api.groq.com/openai/v1"
  104. export LLM_API_KEY="your-groq-key"
  105. export LLM_MODEL="llama-3.3-70b-versatile"
  106. ```
  107. ## Files Created
  108. ```
  109. memory/
  110. observations.md # The main observation log (loaded at startup)
  111. observation-backups/ # Reflector backups (last 10 kept)
  112. .observer-last-run # Timestamp of last observer run
  113. .observer-last-hash # Dedup hash of last processed messages
  114. logs/
  115. observer.log
  116. reflector.log
  117. session-recovery.log
  118. observer-watcher.log
  119. ```
  120. ## Cron Jobs
  121. The setup script creates these OpenClaw cron jobs:
  122. | Job | Schedule | Description |
  123. |-----|----------|-------------|
  124. | `memory-observer` | Every 15 min | Compress recent conversation |
  125. | `memory-reflector` | Hourly | Consolidate if observations are large |
  126. ## Reactive Watcher (Linux only)
  127. The reactive watcher uses `inotifywait` to detect session activity and trigger the observer faster than cron alone. Requires Linux with `inotify-tools` installed.
  128. ```bash
  129. # Install inotify-tools (Debian/Ubuntu)
  130. sudo apt install inotify-tools
  131. # Check watcher status
  132. systemctl --user status total-recall-watcher
  133. # View logs
  134. journalctl --user -u total-recall-watcher -f
  135. ```
  136. ## Cost
  137. Using the default free models via OpenRouter:
  138. - ~$0.00/month (using free-tier models) for typical usage (observer + reflector)
  139. - ~15-30 cron runs/day, each processing a few hundred tokens
  140. - All default models are free tier models
  141. ## Model Notes
  142. The scripts include defensive handling for both `.content` and `.reasoning` fields in API responses. While most models return content in the standard `.content` field, the fallback to `.reasoning` ensures compatibility with models that may use different response formats.
  143. ## How It Works (Technical)
  144. ### Observer
  145. 1. Finds recently modified session JSONL files
  146. 2. Filters out subagent/cron sessions
  147. 3. Extracts user + assistant messages from the lookback window
  148. 4. Deduplicates using MD5 hash comparison
  149. 5. Sends to LLM with the observer prompt (priority-based compression)
  150. 6. Appends result to `observations.md`
  151. 7. If observations exceed the word threshold, triggers reflector
  152. ### Reflector
  153. 1. Backs up current observations
  154. 2. Sends entire log to LLM with consolidation instructions
  155. 3. Validates output is shorter than input (sanity check)
  156. 4. Replaces observations with consolidated version
  157. 5. Cleans old backups (keeps last 10)
  158. ### Session Recovery
  159. 1. Runs at every `/new` or `/reset`
  160. 2. Hashes recent lines of the last session file
  161. 3. Compares against stored hash from last observer run
  162. 4. If mismatch: runs observer in recovery mode (4-hour lookback)
  163. 5. Fallback: raw message extraction if observer fails
  164. ### Reactive Watcher
  165. 1. Uses `inotifywait` to monitor session directory
  166. 2. Counts JSONL writes to main session files only
  167. 3. After 40+ lines: triggers observer (with 5-min cooldown)
  168. 4. Resets counter when cron/external observer runs are detected
  169. ## Customizing the Prompts
  170. The observer and reflector system prompts are in `prompts/`:
  171. - `prompts/observer-system.txt` — controls how conversations are compressed
  172. - `prompts/reflector-system.txt` — controls how observations are consolidated
  173. Edit these to match your agent's personality and priorities.
  174. ---
  175. ## Dream Cycle
  176. The Dream Cycle is an optional nightly agent that runs after hours to consolidate `observations.md`. It archives stale items and adds semantic hooks so nothing useful is actually lost. Context stays lean; everything remains findable.
  177. ### What It Does
  178. - Classifies every observation by impact (critical / high / medium / low / minimal) and age
  179. - Archives items that have passed their relevance threshold
  180. - Adds a semantic hook for each archived item (specific keywords + archive reference)
  181. - Validates the result and rolls back automatically if something goes wrong
  182. ### Features
  183. **Multi-Hook Retrieval** — 4-5 alternative search phrasings per archived item. Searches using different words than the original still find the memory.
  184. **Confidence Scoring** — every observation gets a confidence score (0.0-1.0) and source type (`explicit`, `implicit`, `inference`, `weak`, `uncertain`). High-confidence items are preserved longer; low-confidence items are archived sooner.
  185. **Memory Type System** — 7 types with per-type TTLs: `event` (14d), `fact` (90d), `preference` (180d), `goal` (365d), `habit` (365d), `rule` (never), `context` (30d). Embedded as invisible HTML metadata comments in `observations.md`.
  186. **Observation Chunking** — clusters of 3+ related observations are compressed into single summary entries. Source observations are archived; a chunk hook replaces them. Achieves up to 75% token reduction.
  187. **Importance Decay** — per-type daily decay applied to importance scores before each archival decision. Items that decay below the archive threshold are queued for removal. Rates: `event` (-0.5/day), `fact` (-0.1/day), `preference` (-0.02/day), `rule`/`habit`/`goal` (no decay).
  188. **Pattern Promotion** — scans recent dream logs for recurring themes (3+ occurrences across 3+ separate days). Writes promotion proposals to `memory/dream-staging/` for human review. Use `staging-review.sh` to list, show, approve, or reject proposals. The `context` type is never promoted automatically.
  189. ### Setup
  190. 1. Run `bash skills/total-recall/scripts/setup.sh` — creates Dream Cycle directories automatically.
  191. 2. Add the nightly cron job as a full agent turn:
  192. ```
  193. # Dream Cycle — nightly (3am recommended; adjust to your timezone)
  194. # The dream cycle runs as a full agent turn — NOT as a direct bash call.
  195. # dream-cycle.sh is a file operations helper called BY the agent, not the entry point.
  196. #
  197. # 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
  198. # && openclaw agent --agent main \
  199. # --message "Run the Total Recall Dream Cycle. Follow the instructions in \
  200. # $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md exactly. \
  201. # Use READ_ONLY_MODE=false and DREAM_PHASE=1." \
  202. # --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'
  203. ```
  204. 3. Configure your cron agent using `prompts/dream-cycle-prompt.md` as the system prompt. Recommended models: Claude Sonnet for the Dreamer (analysis + decisions), DeepSeek v3.2 for the Observer (cheap, fast).
  205. 4. Start with `READ_ONLY_MODE=true` for the first few nights. Check `memory/dream-logs/` after each run to verify what it would have archived.
  206. 5. Switch to `READ_ONLY_MODE=false` once satisfied.
  207. ### Configuration
  208. | Variable | Default | Description |
  209. |----------|---------|-------------|
  210. | `DREAM_TOKEN_TARGET` | `8000` | Token target for observations.md after consolidation |
  211. | `READ_ONLY_MODE` | `false` | Set `true` for dry-run analysis without writes |
  212. ### Files
  213. | File | Description |
  214. |------|-------------|
  215. | `scripts/dream-cycle.sh` | Shell helper called **by the agent** (not a standalone runner): preflight, archive, update-observations, write-log, write-metrics, validate, rollback |
  216. | `prompts/dream-cycle-prompt.md` | Agent prompt for the nightly Dream Cycle run |
  217. | `dream-cycle/README.md` | Dream Cycle quick reference |
  218. | `schemas/observation-format.md` | Extended observation metadata format |
  219. ### Directories Created
  220. ```
  221. memory/
  222. archive/
  223. observations/ # Archived items (one .md file per night)
  224. chunks/ # Chunked observation groups
  225. dream-logs/ # Nightly run reports
  226. dream-staging/ # Pattern promotion proposals awaiting human review
  227. .dream-backups/ # Pre-run safety backups
  228. research/
  229. dream-cycle-metrics/
  230. daily/ # JSON metrics per night
  231. ```
  232. ---
  233. ## Troubleshooting
  234. **Observer not running?**
  235. - Check `logs/observer.log` for errors
  236. - Verify `OPENROUTER_API_KEY` is set and valid
  237. - Confirm cron is active: `crontab -l`
  238. **Observations not being loaded at session start?**
  239. - Ensure your agent's startup instructions include reading `memory/observations.md`
  240. - Check `MEMORY_DIR` points to the right location
  241. **Reactive watcher not triggering (Linux)?**
  242. - Run `systemctl --user status total-recall-watcher`
  243. - Check `inotify-tools` is installed: `which inotifywait`
  244. - View watcher logs: `journalctl --user -u total-recall-watcher -f`
  245. **Dream Cycle archiving too aggressively?**
  246. - Enable `READ_ONLY_MODE=true` and review dream logs before going live
  247. - Adjust `DREAM_TOKEN_TARGET` upward to archive less per run
  248. **Dream Cycle not archiving enough?**
  249. - Lower `DREAM_TOKEN_TARGET` to trigger more aggressive consolidation
  250. ---
  251. ## Inspired By
  252. This system is inspired by how human memory works during sleep — the hippocampus (observer) captures experiences, and during sleep consolidation (reflector), important memories are strengthened while noise is discarded.
  253. Read more: [Your AI Has an Attention Problem](https://gavlahh.substack.com/p/your-ai-has-an-attention-problem)
  254. *"Get your ass to Mars." — Well, get your agent's memory to work.*
README.md · README · 317 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Total Recall
  2. > **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](https://github.com/gavdalf/total-recall/issues/22) for details.
  3. Autonomous memory for OpenClaw-style agents.
  4. Total Recall v2.0 keeps the existing v1.x stack intact:
  5. - Observer
  6. - Reflector
  7. - Session Recovery
  8. - Reactive Watcher
  9. - Dream Cycle
  10. 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.
  11. Prerequisites: `python3`, `jq`, `curl`, and `PyYAML`.
  12. Install PyYAML with:
  13. ```bash
  14. python3 -m pip install PyYAML
  15. # or on Debian/Ubuntu:
  16. sudo apt install python3-yaml
  17. ```
  18. `setup.sh` will verify all dependencies are present before continuing.
  19. ## Architecture
  20. ### v1.x memory loop
  21. ```text
  22. Observer -> observations.md -> Reflector -> Dream Cycle -> session recovery / watcher
  23. ```
  24. ### v2.0 Ambient Intelligence Engine
  25. ```text
  26. sensor-sweep
  27. -> enabled connectors emit events to memory/events/bus.jsonl
  28. -> rumination-engine reads new events and writes structured insights
  29. -> preconscious-select scores recent insights into memory/preconscious-buffer.md
  30. -> ambient-actions optionally enriches insights with read-only lookups
  31. -> emergency-surface pushes urgent alerts through configured channels
  32. -> buffer-inject sends the latest buffer back into the live session
  33. ```
  34. The AIE flow is additive. None of the v1.x scripts are removed or replaced.
  35. ## Quick Start
  36. ### v1.x setup
  37. ```bash
  38. git clone https://github.com/gavdalf/total-recall.git
  39. cd total-recall
  40. bash scripts/setup.sh
  41. ```
  42. ### AIE setup
  43. 1. Review [`config/aie.yaml`](config/aie.yaml).
  44. 2. Set `workspace` if you do not want to use the repo root.
  45. 3. Enable only the connectors and notification channels you actually use.
  46. 4. Add credentials to `./.env` or your shell environment.
  47. 5. Run a dry pass:
  48. ```bash
  49. bash scripts/sensor-sweep.sh --dry-run
  50. bash scripts/rumination-engine.sh --dry-run
  51. bash scripts/preconscious-select.sh --dry-run
  52. bash scripts/ambient-actions.sh --dry-run-actions
  53. ```
  54. 6. Schedule the AIE loop once the dry run looks correct:
  55. ```bash
  56. */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
  57. 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
  58. 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
  59. ```
  60. Minimal first-run path:
  61. - leave every connector disabled except `filewatch`
  62. - keep notifications disabled
  63. - set only the model IDs you want under `models`
  64. - add the API key required by your chosen model provider
  65. ## AIE Configuration
  66. All new AIE behavior is controlled by [`config/aie.yaml`](config/aie.yaml).
  67. ### Top-level sections
  68. - `workspace`: root directory for memory, logs, health data, and `.env`
  69. - `paths`: all file and directory locations used by AIE scripts
  70. - `profile`: assistant/user labels and timezone used in prompts and quiet hours
  71. - `api`: shared API metadata such as the outbound HTTP referer
  72. - `models`: model IDs for rumination, classification, enrichment, and ambient actions
  73. - `connectors`: per-connector enable flags, high-importance sender patterns, and connector-specific settings
  74. - `notifications`: quiet hours plus Telegram, Discord, and generic webhook delivery
  75. - `thresholds`: cooldowns, pruning windows, emergency thresholds
  76. - `ambient_actions`: global action toggle plus read-only tool settings
  77. ### Connector toggles
  78. Each connector now checks its own `enabled` flag before doing any work:
  79. - `connectors.calendar.enabled`
  80. - `connectors.todoist.enabled`
  81. - `connectors.ionos.enabled`
  82. - `connectors.gmail.enabled`
  83. - `connectors.fitbit.enabled`
  84. - `connectors.filewatch.enabled`
  85. The orchestrator in [`scripts/sensor-sweep.sh`](scripts/sensor-sweep.sh) also skips disabled connectors.
  86. ### Model settings
  87. Set your own model IDs here:
  88. ```yaml
  89. models:
  90. rumination: <model-id>
  91. classification: <model-id>
  92. enrichment: <model-id>
  93. ambient_actions: <model-id>
  94. ```
  95. The AIE scripts no longer hardcode user-specific model selections.
  96. ### Notification settings
  97. ```yaml
  98. notifications:
  99. quiet_hours:
  100. enabled: true
  101. timezone: UTC
  102. start_hour: 22
  103. end_hour: 7
  104. telegram:
  105. enabled: false
  106. bot_token: ""
  107. chat_id: ""
  108. discord:
  109. enabled: false
  110. webhook_url: ""
  111. webhook:
  112. enabled: false
  113. url: ""
  114. headers: {}
  115. ```
  116. `emergency-surface.sh` will only send through enabled channels. If no channel is enabled, it exits without error.
  117. ### Path settings
  118. Everything that was previously tied to `~/clawd` is now configurable under `paths`, including:
  119. - event bus
  120. - sensor state
  121. - rumination directory
  122. - preconscious buffer
  123. - health data
  124. - log directory
  125. - `.env` file
  126. - optional web search helper path
  127. ### Threshold settings
  128. Key defaults:
  129. ```yaml
  130. thresholds:
  131. rumination_cooldown_seconds: 1800
  132. rumination_staleness_seconds: 14400
  133. sensor_prune_hours: 48
  134. emergency:
  135. importance: 0.85
  136. expires_within_seconds: 14400
  137. max_alerts_per_day: 2
  138. ```
  139. ### Connector reference
  140. `calendar`
  141. - `account`
  142. - `calendar_id`
  143. - `lookahead_days`
  144. - `max_events`
  145. - `keyring_password`
  146. `gmail`
  147. - `account`
  148. - `query` (default `newer_than:3h`)
  149. - `max_messages`
  150. - `keyring_password`
  151. `ionos`
  152. - `account`
  153. - `query` (`recent` or `unread`)
  154. - `max_messages`
  155. `connectors.scoring`
  156. - `model`
  157. - `batch_size`
  158. - `cache_threshold`
  159. - `sender_cache_file`
  160. `connectors.high_importance_senders`
  161. - list of sender substrings that should raise email importance (default: empty)
  162. - add patterns for senders you care about most: your employer, accountant, school, doctor, bank, tax authority, etc.
  163. - example: `["mycompany", "school", "hospital", "accountant", "bank"]`
  164. `fitbit`
  165. - `sleep_target_hours`
  166. - `short_sleep_minutes`
  167. - `great_sleep_minutes`
  168. - `watch_off_minutes`
  169. - `watch_uncertain_minutes`
  170. - `resting_hr_threshold`
  171. - `weight_target_lbs`
  172. - `steps_milestone`
  173. `filewatch`
  174. - `watch_files`
  175. ### Ambient action reference
  176. `ambient_actions`
  177. - `enabled`
  178. - `max_actions`
  179. - `action_budget_seconds`
  180. - `weather_url`
  181. - `places.default_lat`
  182. - `places.default_lng`
  183. - `places.default_limit`
  184. `ambient_actions.tool_settings`
  185. - `calendar_lookup.gog_account`
  186. - `calendar_lookup.gog_keyring_password`
  187. - `gmail_search.gog_account`
  188. - `gmail_search.gog_keyring_password`
  189. - `gmail_read.gog_account`
  190. - `gmail_read.gog_keyring_password`
  191. - `ionos_search.account`
  192. - `fitbit_data.enabled`
  193. - `openrouter_balance.enabled`
  194. - `web_search.enabled`
  195. - `web_search.script`
  196. - `places_lookup.enabled`
  197. ### Action resolution system
  198. `ambient-actions.sh` reads enriched rumination insights and decides what to do with them. Five action types are supported, each with guardrails to prevent runaway behaviour:
  199. | Action | Description | Guardrails |
  200. |--------|-------------|------------|
  201. | `ask` | Surfaces a question to the user via preconscious buffer | Max 3/run |
  202. | `learn` | Stores a confirmed fact to `learned-facts.json` | Importance >= 0.7, dedup, max 5/run |
  203. | `draft` | Prepares content for user review in `drafts/` | Importance >= 0.75, max 2/run |
  204. | `notify` | Sends an urgent alert via emergency-surface | Importance >= 0.85, max 2/day, quiet hours respected |
  205. | `remind` | Creates a time-based nudge in `reminders.jsonl` | Auto-surfaces when due, max 3/run |
  206. #### Runtime files
  207. The AIE creates several files in `memory/rumination/` during operation:
  208. - `learned-facts.json` — facts the engine has confirmed and stored autonomously
  209. - `reminders.jsonl` — pending time-based nudges
  210. - `drafts/` — content prepared for user review (one `.md` file per draft)
  211. - `cycle-state.json` — working memory: tracks lookups between cycles with TTL-based dedup (4hr window)
  212. #### Agent startup
  213. For best results, have your agent read `memory/rumination/learned-facts.json` and check `memory/rumination/drafts/` at session start. This surfaces what the AIE has learned and prepared between sessions.
  214. ## Existing v1.x Notes
  215. The original observer / reflector / dream-cycle flow still works as before. The v1.x scripts continue to read their existing environment variables and paths. The new AIE config does not remove that compatibility layer.
  216. See:
  217. - [`dream-cycle/README.md`](dream-cycle/README.md)
  218. - [`SKILL.md`](SKILL.md)
  219. - [`docs/architecture.md`](docs/architecture.md)
  220. ## Repository Layout
  221. | Path | Purpose |
  222. |------|---------|
  223. | `scripts/observer-agent.sh` | v1.x observer |
  224. | `scripts/reflector-agent.sh` | v1.x reflector |
  225. | `scripts/dream-cycle.sh` | v1.x nightly consolidation helper |
  226. | `scripts/sensor-sweep.sh` | AIE connector orchestrator |
  227. | `scripts/rumination-engine.sh` | AIE reasoning pass |
  228. | `scripts/preconscious-select.sh` | buffer scorer/selector |
  229. | `scripts/ambient-actions.sh` | read-only enrichment loop |
  230. | `scripts/emergency-surface.sh` | urgent alert surfacing |
  231. | `scripts/buffer-inject.sh` | inject buffer back into active session |
  232. | `scripts/connectors/*.sh` | pluggable AIE sensors |
  233. | `config/aie.yaml` | AIE runtime configuration |
  234. ## License
  235. MIT. See [`LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.