Memory

Overview

The memory system stores conversation history, extracted facts, artifacts, and skill usage statistics in a local SQLite database with full-text search (FTS5). It integrates with the agent, cron jobs, gateway chats, and the cloud workspace.

Memory lives under ~/.arcana/data/ by default (override with dataDir in config or ARCANA_HOME).

Commands

Searching memory

Arcana uses SQLite FTS5 for fast full-text search across all stored sessions and facts.

# Search for anything
arcana memory search "deployment config"

# Search with a specific query
arcana memory search --query "authentication flow"

# Search session transcripts
arcana memory sessions --limit 10

Search returns ranked results with timestamps, source session, and relevance scores. The agent also uses search internally when answering questions about past work.

Facts

During conversations, the agent automatically extracts key facts — decisions, preferences, patterns, and configuration details. These facts persist across sessions and are used to provide context-aware responses.

# List all facts
arcana memory facts

# Show stats
arcana memory stats

Fact examples:

• project.uses_bun — "Project uses Bun as the runtime"
• deploy.target — "Deploys to Cloudflare Workers"
• user.theme — "User prefers dark theme"
• team.review_style — "Team prefers concise PR reviews"

Cloud sync

When logged in with arcana console login, you can sync facts between your local machine and the Arcana cloud workspace. This is useful for cross-machine access and team collaboration.

# Push local facts to cloud
arcana memory push

# Pull cloud facts to local
arcana memory pull

# Bidirectional sync
arcana memory sync

Via the Proxy API

You can also manage cloud memory directly through the API:

# List cloud facts
curl -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  https://proxy-arcana.otnelhq.com/v1/memory

# Upsert facts
curl -X PUT -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"facts":[{"key":"user.theme","value":"dark","confidence":1}]}' \
  https://proxy-arcana.otnelhq.com/v1/memory

# Delete a fact
curl -X DELETE -H "Authorization: Bearer $ARCANA_PROXY_KEY" \
  https://proxy-arcana.otnelhq.com/v1/memory/user.theme

How memory works

• Every session stores conversation history in the local SQLite database.
• After each session, the agent extracts facts and patterns into the fact store.
• FTS5 indexing enables fast full-text search across all sessions and facts.
• Skill usage is tracked automatically — the agent learns which skills are most useful over time.
• Cron jobs and gateway chats share the same memory store — context persists across interfaces.
• Cloud sync is optional and requires a Pro or Enterprise license.

Configuration

{
  "memory": {
    "enabled": true,
    "maxSessions": 1000
  }
}

See Configuration for the full reference.

Data location

All memory data is stored under ~/.arcana/data/: