Memory: How Arcana Remembers Across Sessions

Every new conversation with an AI starts from zero. You re-explain your project, re-state your preferences, re-describe the codebase. Arcana's memory system changes this: context persists locally, and future sessions can access it.

This is one of the most common frustrations with AI assistants. You spend 20 minutes explaining your project's architecture, your coding conventions, and the specific constraints of the task. Then you close the terminal and start again tomorrow. The agent remembers nothing. You re-explain everything. The repetition is exhausting and wasteful.

Arcana's memory system breaks this cycle. Information from previous sessions persists locally. When you start a new session, the agent loads relevant memory automatically. It knows your project structure, your preferences, and the decisions from previous work. You pick up where you left off, not where you started.

What Memory Stores

Arcana's memory captures:

• Project context. File structure, key files, and configuration that the agent discovered during previous sessions.
• User preferences. Coding style, formatting rules, and behavioral preferences you expressed.
• Session summaries. Compressed summaries of previous sessions, including decisions made and problems solved.
• Tool results. Cached outputs from search, file reads, and other tools that may be needed again.

Local by Default

All memory is stored locally. Nothing is sent to external servers. The memory store is a SQLite database in your Arcana home directory. This means memory is fast (no network latency) and private (your context never leaves your machine).

The memory database location depends on your operating system:

• Linux: ~/.arcana/memory.db
• macOS: ~/.arcana/memory.db
• Windows: %USERPROFILE%\.arcana\memory.db

You can back up this file to preserve your memory across machine migrations, or delete it to start fresh.

Cloud Sync

For users who work across machines, Arcana offers optional cloud sync. When enabled, memory syncs via your Arcana account. Sync is end-to-end encrypted: Arcana's servers never see your memory contents in plaintext.

# Memory is stored locally by default
# Check memory stats
arcana memory stats

# Search memory
arcana memory search "deployment config"

Memory in Action

When you start a new session, the agent loads relevant memory automatically. If you are working on a project the agent has seen before, it remembers the file structure, your preferences, and the decisions from previous sessions. You do not need to say "I prefer tabs over spaces" twice.

Manual Control

You can manage memory directly:

# See what the agent remembers
arcana memory list

# Forget a specific topic
arcana memory forget "old-project"

# Clear all memory
arcana memory clear

Memory vs. Context Window

Memory is not the same as context window. The context window holds the current conversation. Memory holds cross-session data. The agent uses memory to bootstrap new sessions, not to extend the current one. Session compaction handles in-session context management; memory handles across-session persistence.

This distinction matters for how you think about each system:

• Context window is short-term memory. It holds everything from the current conversation. It is fast, always up to date, and limited by the model's token count.
• Memory is long-term memory. It holds cross-session data. It is slower (requires loading at session start), potentially stale, and limited by disk space.
• Session compaction is the bridge between the two. It compresses the current conversation to fit within the context window, preserving the most important information.

Together, these three systems give the agent a complete memory architecture: short-term (context window), medium-term (compaction summaries), and long-term (memory store).