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

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

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

• 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 and Session memory 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

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

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:

defaults:
  memory: scoped
  memory_scope:
    read: [global, team, workflow]
    write: workflow
    ttl_hours: 72
    promote: manual

Promote after a workflow run:

arka workflow run review-and-ship --task "..." --promote-final

See Agent Teams and 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 or the arka_agent_hub MCP tool with memory_sources / import_memory.