> ## 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.

# Long-term memory with Supermemory sync

> Persist facts across Arka sessions using Supermemory cloud sync with an automatic local cache fallback, plus natural-language remember and recall commands.

Arka remembers facts across sessions. With a [Supermemory](https://supermemory.ai) API key, memories sync to the cloud; otherwise Arka falls back to a local cache automatically.

## Commands

| Command                          | Example                                   |
| -------------------------------- | ----------------------------------------- |
| `arka memory remember`           | `arka memory remember I prefer Hindi TTS` |
| `arka memory recall`             | `arka memory recall what TTS do I prefer` |
| `arka supermemory status`        | Show backend mode (api / local)           |
| `arka supermemory remember`      | Explicit cloud remember                   |
| `arka supermemory recall`        | Explicit cloud recall                     |
| `arka "semantic memory reindex"` | Rebuild semantic index on local cache     |

## Natural language

```bash theme={null}
arka "remember that my dog is named Max"
arka "what do you remember about Max"
arka "I prefer Hindi TTS"    # auto-detected with MEMORY_AUTODETECT=1
```

## Configuration

```env theme={null}
SUPERMEMORY_API_KEY=...
MEMORY=auto                  # auto | supermemory | local
MEMORY_AUTODETECT=1          # symbolic autodetect from chat/voice
```

Recalled context is injected into `arka ask`, research, and agent loops automatically.

## Context layers

Arka uses several complementary context stores. Pick the layer that matches your use case:

| Layer             | Command / store                     | When to use                                                |
| ----------------- | ----------------------------------- | ---------------------------------------------------------- |
| Facts (long-term) | `arka memory remember`, Supermemory | Preferences, stable knowledge across weeks                 |
| Session notes     | `arka session-memory`               | Markdown notes, daily journaling (`MEMORY.md`)             |
| Channel turns     | `arka session`                      | Per chat/thread continuity (webhook, CLI, Telegram bridge) |
| Chat session      | automatic in `arka ask`             | Current conversation window in-process                     |

```mermaid theme={null}
flowchart LR
  subgraph ingress [Ingress]
    Webhook[Webhook POST]
    CLI[arka ask / agent]
  end
  subgraph stores [Stores]
    Channel[message_session JSON]
    Facts[Supermemory / memory.json]
    Notes[session_memory markdown]
  end
  subgraph agent [Agent prompt]
    Prompt[LLM context]
  end
  Webhook --> Channel
  CLI --> Channel
  Facts --> Prompt
  Notes --> Prompt
  Channel --> Prompt
```

* **Facts** — searched by goal text; highest priority in `memory_context_for()`
* **Session notes** — markdown files under `~/.config/arka/agent-memory/`
* **Channel turns** — JSON per `channel:chat_id`; shared between webhook and CLI when IDs match
* **Chat session** — ephemeral in-memory history for the current `arka ask` run

See [Channel sessions](/guides/hermes-features) and [Session memory](/guides/openclaw-features) for setup.

## Unified memory

When `UNIFIED_MEMORY=1` (default), Arka routes recall through a single facade that aggregates facts, session notes, and channel turns — without duplicating channel context in `arka ask`.

| Command                       | Example                                       |
| ----------------------------- | --------------------------------------------- |
| `arka memory remember`        | `arka memory remember I prefer dark mode`     |
| `arka memory recall`          | `arka memory recall "what theme do I prefer"` |
| `arka memory status`          | Show counts across all layers                 |
| `arka memory scratchpad list` | List scoped workflow entries                  |
| `arka memory promote <id>`    | Elevate scratchpad entry to global facts      |

```env theme={null}
UNIFIED_MEMORY=1    # default on; set 0 to use legacy per-layer recall only
```

Layer routing with `--layer auto` (default):

* **Facts** — preferences, stable knowledge → Supermemory / `memory.json`
* **Notes** — journaling, meetings → `session_memory` markdown
* **Channel** — conversation turns → `message_session` JSON

Existing commands (`arka session-memory`, `arka session`) still work alongside unified memory.

## Scoped memory and provenance (v3)

Shared memory is useful only when trust boundaries are explicit. Scoped memory adds **trust tiers**, **write-time provenance**, and a **workflow scratchpad** separate from global facts.

| Trust tier | Scope              | Typical use                                |
| ---------- | ------------------ | ------------------------------------------ |
| `global`   | User-curated facts | Preferences, promoted workflow outputs     |
| `team`     | Same team name     | Cross-workflow team context (ClawBox edge) |
| `workflow` | Team + workflow    | Step handoff within one workflow           |
| `run`      | Single run ID      | Ephemeral turn context                     |

### Commands

| Command                                       | Example                                  |
| --------------------------------------------- | ---------------------------------------- |
| `arka memory scope status`                    | Trust cap, scratchpad count              |
| `arka memory scratchpad list`                 | List scoped entries                      |
| `arka memory scratchpad list --team research` | Filter by team                           |
| `arka memory promote <id>`                    | Elevate scratchpad entry to global facts |

### Configuration

```env theme={null}
ARKA_MEMORY_TRUST_MAX=run    # cap recall/export: global | team | workflow | run (default run = all tiers)
ARKA_HUB_MEMORY_SCOPE=team:clawbox   # limit Agent Hub export to one team
MEMORY_SCRATCHPAD_TTL_HOURS=72  # expire workflow scratchpad entries
```

### Agent teams integration

Teams with `defaults.memory: scoped` use policy-filtered recall and write step outputs to the scratchpad (not global facts) unless you promote:

```yaml theme={null}
defaults:
  memory: scoped
  memory_scope:
    read: [global, team, workflow]
    write: workflow
    ttl_hours: 72
    promote: manual
```

Promote after a workflow run:

```bash theme={null}
arka workflow run review-and-ship --task "..." --promote-final
```

See [Agent Teams](/guides/agent-teams) and [Agent Hub](/guides/agent-hub) for edge deployment (Jetson / ClawBox).

To pull memory **from other IDEs into Arka** (Cursor rules, Codex notes, hub exports), use [Agent Hub — Memory import](/guides/agent-hub#memory-import) or the `arka_agent_hub` MCP tool with `memory_sources` / `import_memory`.


## Related topics

- [Agent Hub](/guides/agent-hub.md)
- [Channel sessions and sub-agent delegation](/guides/hermes-features.md)
- [Session memory, heartbeat, and skill gates](/guides/openclaw-features.md)
- [Daily and tech brief](/guides/daily-brief.md)
- [Arka — AI terminal agent documentation](/index.md)