> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# Session memory, heartbeat, and skill gates

> OpenClaw-inspired Arka features — markdown session memory, agent heartbeat, and skill manifest gates for requires, OS, and permissions.

Arka includes several **OpenClaw-inspired** features (not a separate OpenClaw product integration). They add persistent session notes, agent health tracking, and declarative skill gates for third-party plugins.

## Session memory

Markdown-based session notes stored under `~/.config/arka/agent-memory/`:

* `MEMORY.md` — long-term notes (pruned automatically)
* `daily/YYYY-MM-DD.md` — per-day session notes

```bash theme={null}
arka session-memory append "Prefers morning standups at 9am"
arka session-memory append "Always use dark terminal theme" --long-term
arka session-memory search standup
arka session-memory context "plan my morning routine"
arka session-memory status
arka session-memory clear                # today's daily notes
arka session-memory clear --long-term    # reset MEMORY.md
arka session-memory clear --all
```

Recalled context is injected into agent loops via `context_for()` when `SESSION_MEMORY=1`.

### Environment variables

| Variable                    | Default                       | Purpose                                |
| --------------------------- | ----------------------------- | -------------------------------------- |
| `SESSION_MEMORY`            | `1`                           | Enable (`0` to disable)                |
| `SESSION_MEMORY_DIR`        | `~/.config/arka/agent-memory` | Storage root                           |
| `MEMORY_LONGTERM_MAX_LINES` | `100`                         | Max lines kept in `MEMORY.md`          |
| `MEMORY_AUTO_LONGTERM`      | `0`                           | Auto-promote every append to long-term |

Notes are sanitized before storage — injection patterns and unsafe content are blocked.

## Heartbeat

Tracks last agent activity, security flags, routine count, and memory stats.

```bash theme={null}
heartbeat status
heartbeat ping goal.completed
heartbeat history
heartbeat history --json --limit 10
```

Heartbeat data is written to `~/.cache/fish-agent/heartbeat.json`. Each `ping()` appends to a bounded `history` ring (default 20 events; override with `HEARTBEAT_HISTORY`). Subsystems like session memory and routines call `ping()` automatically on activity.

## Skill manifest gates

Third-party plugins can declare **OpenClaw-style gates** in `skill.json`. Arka applies them during discovery, routing, and execution.

### Top-level fields

```json theme={null}
{
  "name": "my_skill",
  "requires": {
    "bins": ["ffmpeg"],
    "anyBins": ["docker", "podman"],
    "env": ["MY_API_KEY"]
  },
  "os": ["darwin", "linux"],
  "permissions": ["read", "network"]
}
```

### `metadata.openclaw` (or `metadata.arka` / `metadata.hermes`)

The same fields can live under `metadata.openclaw`, `metadata.arka`, or `metadata.hermes` for compatibility with OpenClaw- and Hermes-style manifests:

```json theme={null}
{
  "name": "my_skill",
  "metadata": {
    "openclaw": {
      "requires": { "env": ["MY_API_KEY"] },
      "os": ["darwin"],
      "permissions": ["network"]
    }
  }
}
```

Arka merges any of these metadata blocks into the top-level `requires`, `os`, and `permissions` fields at parse time.

### Gate behavior

| Gate               | Blocks when                                     |
| ------------------ | ----------------------------------------------- |
| `os`               | Current platform not listed                     |
| `requires.bins`    | Binary not found on `PATH`                      |
| `requires.anyBins` | None of the listed binaries found               |
| `requires.env`     | Environment variable unset                      |
| `permissions`      | Permission not in `SKILL_PERMISSIONS` allowlist |

Gated skills are:

* **Marked** in `arka skills list` with `[gated: reason]`
* **Skipped** by `match_command()` so routing does not match unavailable plugins
* **Blocked** at `run_skill()` as a safety net

### Environment variables

| Variable            | Default                    | Purpose                                 |
| ------------------- | -------------------------- | --------------------------------------- |
| `SKILL_PERMISSIONS` | `read,write,network,shell` | Allowed permission tags                 |
| `SKILLS_PATH`       | —                          | Extra directories to search for plugins |

See also: [Installing plugins](/guides/plugins) and the example at `src/arka/skills/examples/demo_echo/skill.json`.

## Related security

Routines and webhooks apply separate hardening layers:

* `ROUTINES_SECURITY=1` — symbolic action checks on scheduled tasks
* Webhook inbound verification blocks injection payloads

These work alongside the global `SECURITY`, `SECURITY_LLM`, and `SECURITY_ACTIONS` flags documented in [Security](/concepts/security).


## Related topics

- [Channel sessions and sub-agent delegation](/guides/hermes-features.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Agent Hub](/guides/agent-hub.md)
- [How to code with Arka](/guides/code-with-arka.md)
- [Arka — AI terminal agent documentation](/index.md)