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

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

Arka injects recalled context 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

- [Session memory, heartbeat, and skill gates](/guides/openclaw-features.md)
- [Agent Hub](/guides/agent-hub.md)
- [Channel sessions and sub-agent delegation](/guides/hermes-features.md)
- [Daily and tech brief](/guides/daily-brief.md)
- [Supermemory code RAG](/guides/supermemory.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.