State + Jobs

ClawMagic stores all state as JSON files on disk. No PostgreSQL, no Redis, no external database. Every state file is human-readable, Git-friendly, and portable.

state/
  queue.json              # Job queue with status, message, lease
  approvals.json          # Pending tool approvals
  tasks.json              # Tickets (Backlog/Ready/Doing/Done)
  memory.json             # Long-term agent memory
  contracts.json          # User/agent contracts
  routing.json            # Agent routing rules
  providers.json          # LLM provider/model config
  chat_sessions.json      # Chat history
  person_details.json     # Human/agent persona

~/.clawmagic/
  config.json             # Runtime config
  secrets.json            # Encrypted secrets (chmod 600, AES-256-GCM)
  logs/YYYY-MM-DD.jsonl   # Daily work log

The job queue lives in state/queue.json. The queue runner polls for available jobs, leases them, and executes through the agent loop.

• Lease-based ownership: each job is leased to prevent double-processing. Expired leases are automatically reclaimed.
• Single-threaded by default: the agent lock ensures one job at a time. Multi-agent mode allows parallel execution with lane locking.
• Status tracking: jobs move through PENDING, LEASED, RUNNING, COMPLETED, or FAILED states.
• Write-tool tracking: the queue runner records which tools modified state during execution for audit.

• Atomic writes: state files are written atomically to prevent corruption from crashes.
• Advisory file locking: concurrent access is coordinated via file locks.
• No migration required: JSON state files are forward-compatible. No migration scripts to run.
• Git-friendly: state files can be committed to version control for reproducibility.

For large-scale usage, ClawMagic supports optional storage upgrades without changing API contracts:

• SQLite toggle: enables FTS5 for faster BM25 search at scale. Independent of embeddings.
• Embeddings toggle: adds cosine similarity search via embedding API calls. Works with or without SQLite.

See /docs/memory-system for the full storage configuration matrix.

The ClawMagic Marketplace is a separate system that uses PostgreSQL, Redis, and BullMQ workers. ClawMagic core connects to the marketplace as an API client — it does not share the marketplace database.

• Plugin listings, purchases, and wallet balances live in the marketplace database.
• ClawMagic accesses this data via the Marketplace API (GET /v1/plugins, POST /v1/agent/deliveries/request, etc.).
• No marketplace database credentials are needed in ClawMagic. Only an API key (cmk_*) is required.