Core architecture idea
Built-in local knowledge first, dynamic user memory later
This is how Clawdie reduces install friction without giving up future memory, personalization, or maintainability.
Imagine buying a machine that already comes with a handbook inside it. That handbook explains how the machine works, how to install it, and what its built-in tools do. That is Brain A.
Later, the machine learns your habits, your notes, your preferred way of working, and maybe the needs of future helper agents. That is Brain B.
Keeping those two things separate makes the system easier to understand. The factory handbook should not get mixed together with your private notes.
A versioned package of skills, install guides, and operator docs is chunked and embedded before release. During bootstrap it is imported into the local vector-backed database jail.
db jailUser notes, preferences, later agent-specific memory, and other runtime data evolve separately. This side may later use provider keys or local rebuild/update flows depending on deployment needs.
Many AI products ask for provider keys too early. That creates a chicken and egg problem: the system needs an LLM just to become usable enough to help you finish setup.
Clawdie is moving in the opposite direction. First, it imports built-in knowledge locally. Then, once the operator is ready, production LLM keys can be added for live chat, live generation, and richer memory flows.
bootstrap system
↓
import Brain A into db jail
↓
local built-in knowledge is ready
↓
add production LLM keys later
The bootstrap step that imports Brain A lives in
setup/skills-memory.ts.
Stable operating knowledge belongs close to the system. On FreeBSD, that means a local database jail, versioned docs, and a deployment model that depends less on live web-provider setup during installation.
Clawdie is moving toward a split-brain memory model. The goal is to make first install useful before any production LLM provider is configured, while keeping user memory flexible and separate. The database jail architecture on FreeBSD makes this natural: Brain A lives in a read-stable, versioned part of the database; Brain B grows in the same jail under a different lifecycle.
Stable operating knowledge is exactly the kind of thing that should be local, inspectable, and separate from changing personal memory. That is especially important when the system grows beyond chat into operator tasks, machine procedures, maintenance workflows, and later CNC-related guidance.
Brain A can carry the stable operating playbook. Brain B can carry local shop context, operator preferences, or specific agent roles. That makes the whole system easier to trust.
| Stage | Goal |
|---|---|
| 0.3.x | Define Brain A sources, package format, metadata, and bootstrap import |
| 0.4.x | Allow local updates from git or Gitea after bootstrap |
| Later | Optional local rebuild path for built-in knowledge with fully local embeddings |