Temporal Halo

Name: Temporal Halo
Rating: 3.5 (1 reviews)
Author: shayne

By shayne 👁 50 views ▲ 0 votes

OpenClaw Temporal Halo plugin: always-on HALO.md + cron-driven dreaming

GitHub

Install

openclaw plugins install @shayne/openclaw-temporal-halo

README

# OpenClaw Temporal Halo

Temporal Halo is an OpenClaw plugin that maintains a living markdown document (`HALO.md`) describing the user’s recent past, present, and future. The plugin injects `HALO.md` into every agent turn and provides a scheduled “dream” flow to keep it up to date.

This plugin is intentionally tool/skill agnostic: it does not hardcode email/calendar/chat APIs. Instead, the dream step tells the agent what to look for (calendar, email, messages, etc.) and the agent chooses from whatever skills/tools you have installed and authorized.

## What You Get

- Always-on context injection
  - `HALO.md` is prepended to every agent turn (high convenience, higher privacy risk).
- Dream mode (cron-triggered, agent-driven)
  - Runs periodically (recommended: every 30 minutes)
  - Refreshes `HALO.md` by pulling from your connected digital life sources (calendar/email/messages/etc.)
- Size guardrails
  - `HALO.md` budget: 25,000 chars
  - If a dream draft is >25k on first publish attempt, the agent is instructed to compact to <=20k and retry.
  - If it’s still >25k on the second attempt, the plugin warns the user (system event) and does not write an oversized file.

## Install

From npm (recommended):

```bash
openclaw plugins install @shayne/openclaw-temporal-halo
openclaw plugins enable openclaw-temporal-halo
```

From a local checkout (development):

Link-install the plugin (no copy) so edits take effect immediately:

```bash
openclaw plugins install -l .
openclaw plugins enable openclaw-temporal-halo
```

Verify it loaded:

```bash
openclaw plugins info openclaw-temporal-halo
```

## Configure

Plugin config lives under `plugins.entries.openclaw-temporal-halo.config` in your OpenClaw config (typically `~/.openclaw/openclaw.json`).

Example:

```json5
{
  plugins: {
    entries: {
      "openclaw-temporal-halo": {
        enabled: true,
        config: {
          // default: ~/.openclaw/temporal-halo/HALO.md
          haloPath: "~/.openclaw/temporal-halo/HALO.md",
          dreamMarker: "[temporal-halo:dream]",
          maxChars: 25000,
          compactTargetChars: 20000,
          debug: false,
        },
      },
    },
  },
}
```

## Set Up Dreaming (OpenClaw Cron)

Temporal Halo uses OpenClaw’s built-in cron scheduler (no OS cron).

Create a repeating isolated job (every 30 minutes). Keep the cron message short: the plugin injects the detailed dream instructions automatically.

```bash
openclaw cron add \
  --name "Temporal Halo: Dream" \
  --every "30m" \
  --session isolated \
  --no-deliver \
  --message "[temporal-halo:dream] Refresh HALO.md and publish via temporal_halo_publish."
```

Run it once to test:

```bash
openclaw cron list
openclaw cron run <job-id> --timeout 300000
```

## Connect Your Sources (Calendar/Email/Messages)

If your `HALO.md` contains mostly meta and not real-world context, the dream run probably could not access calendar/email/messages.

- See what skills are available and eligible:
  - `openclaw skills list --eligible --verbose`
- Make sure the relevant skills are installed in the agent workspace and are authorized.
- If a skill requires interactive auth, run a one-off dream in an interactive session first, then rely on cron.

## Tool Allowlists (If You Use Them)

If you have a strict tool allowlist configured (global `tools.allow` or per-agent `agents.list[].tools.allow`), make sure you allow either:

- `temporal_halo_publish` (tool name), or
- `openclaw-temporal-halo` (plugin id), or
- `group:plugins` (all plugin tools)

## HALO.md Structure (Guideline)

The dream step maintains a stable schema with:

- Present (Now to 24h)
- Near Future (Next 14d)
- Medium Future (15–60d)
- Long Horizon (60d+ important)
- Recent Past (Last 14d)
- Retrieval Recipes (tool/skill agnostic pointers)
- Key Identifiers (full values allowed: confirmations, locators, etc.)

## Security Notes

- `HALO.md` may contain sensitive personal identifiers and is injected into every agent turn.
- Treat this as equivalent to pasting `HALO.md` into every prompt.
- If you don’t want that, don’t enable this plugin.

## Troubleshooting

- `openclaw cron run` times out:
  - The CLI default timeout is 30s. Use `--timeout 300000` (or higher).
- `HALO.md` doesn’t include calendar/email:
  - Check `openclaw skills list --eligible --verbose`.
  - Ensure those skills are installed and authenticated for the agent running the cron job.

## Development

This repo uses `mise` to manage tooling and tasks.

```bash
mise install
mise run lint
mise run check-types
mise run test
```

## Publishing (Maintainers)

Preferred: GitHub Actions Trusted Publishing (OIDC) in `.github/workflows/release.yml`.

- Push a tag `vX.Y.Z` to publish `latest` (the workflow verifies the tag matches `package.json`).
- Push to `main` to publish a `dev` dist-tag (with an auto-generated dev version).

Manual fallback (publishes from your machine; requires `npm login` and publish rights):

```bash
mise run publish-npm
```

## License

MIT. See `LICENSE`.

tools