Localhost-First
ClawMagic is a node-based system designed to run on your machine first. The default binding is 127.0.0.1 only. No cloud account required, no external service calls on first boot. You own your runtime.
- Default mode binds to localhost with no auth overhead for local development.
- Remote mode is available with API token auth and explicit
allow_remote=true. - CORS is restricted to
localhost/127.0.0.1/[::1]in local mode. - Docker-compose binds to localhost by default.
Flat File, Database Optional
Out of the box, ClawMagic stores memory and state in JSONL flat files. No database install required. No external services. Git-friendly, portable, inspectable.
When you need more, toggle on SQLite for faster disk I/O with large document counts. Toggle on embeddings for semantic search. Each toggle is independent. Neither requires the other.
| SQLite | Embeddings | Storage | Search | API Cost |
|---|---|---|---|---|
| Off | Off | JSONL | BM25 | Zero |
| Off | On | JSONL | BM25 + Cosine | Embedding API calls |
| On | Off | SQLite | BM25 (FTS5) | Zero |
| On | On | SQLite + vec | BM25 + Cosine | Embedding API calls |
BYOK (Bring Your Own Key)
Users pay for every token. The architecture respects that.
- Conversational, not context-dumping. ClawMagic retrieves what is needed, when it is needed, in focused amounts. Larger context is available on opt-in expansion, never forced by default.
- Mimics reality. Like a person working through a task: check what you know, verify before acting, learn from outcomes. Not a machine blindly executing with maximum context.
- AI-driven, budget-aware. Intelligent routing, self-verification, and adaptive learning while respecting token budgets. Performance comes from smarter retrieval, not bigger payloads.
- Every toggle answers “do I need this?” The answer is always “no, but here is what it adds and what it costs.”
Node-Based Architecture
ClawMagic runs as a Node.js process on your machine. There is no mandatory cloud infrastructure, no container orchestration required, and no vendor lock-in.
- Single process for the agent runtime. Start it, talk to it, shut it down.
- Plugins load locally. No remote execution unless you opt in.
- Memory lives on disk next to your project. Back it up with Git if you want.
- Scale horizontally when you need to, not because the architecture forces it.
Hard Constraints
These rules are enforced across the entire codebase. They are not guidelines. They are constraints.
- Default must be zero-dependency. Out of the box: JSONL storage + BM25 search. No SQLite, no embedding API, no external services.
- No forced external API for search. Default search works with zero API calls. Embedding search is opt-in only.
- File-based first. Default storage is JSONL flat files. Git-friendly. SQLite is an optional performance toggle.
- No model-generated SQL. Even with SQLite enabled, the runtime never requires the LLM to write queries.
- Existing API contracts preserved. All memory endpoints keep the same request/response shapes regardless of which toggles are on.
- Independent toggles. SQLite and embeddings are unrelated technologies. Either can be on or off without affecting the other.