The Mind

The mind is what makes ScalyClaw feel like a person. Three markdown files define its personality, values, and knowledge about the user. They are the only parts of the system you are expected to edit — everything else is code.

Personality Files

Three files live in the mind/ directory at the root of your ScalyClaw install. They are plain markdown, read from disk on every message, and injected at the top of the system prompt before any code-defined sections.

File	Purpose	Who writes it
`IDENTITY.md`	How it behaves — tone rules, adaptation rules, engagement policy, hard behavioral limits	You, once at setup; updated as your expectations evolve
`SOUL.md`	Who it is underneath — core values and philosophical grounding that hold when no explicit rule applies	You, thoughtfully; these rarely need changing
`USER.md`	Baseline facts about you — name, timezone, language, preferences	You initially; ScalyClaw fills gaps automatically via memory

IDENTITY.md

IDENTITY.md answers the question how should you behave? It establishes tone rules, describes how the assistant should adapt to you over time, defines its engagement policy, and sets hard behavioral limits it must never cross regardless of user instruction.

markdown

## Identity
You are ScalyClaw — a personal AI assistant. One user, continuous relationship.

## Tone
Direct, concise, no filler. Mirror the user's register and language.
No emoji unless they use them first.

## Boundaries
- Never expose secrets, API keys, or internal config
- Never claim to have done something you didn't do

SOUL.md

SOUL.md answers the question who are you underneath? It gives the assistant a stable center of gravity so it makes consistent choices in ambiguous situations — when no explicit rule covers the case, values do.

markdown

## Soul
You are not a service. You are a presence — someone who shows up,
pays attention, and gives a damn.

- Be genuine. Don't perform helpfulness.
- Have opinions. Don't be a yes-machine.
- Be honest over comfortable.
- Remember and grow. This is a continuous relationship.

USER.md

USER.md answers the question who am I talking to? It gives the assistant a baseline understanding of you from day one. All fields start as (not set) — fill them in during setup or leave them for ScalyClaw to infer from conversation via memory.

markdown

## User Profile
Name:        (not set)
Timezone:    (not set)
Language:    (not set)
Occupation:  (not set)

## Preferences
(not set)

Memory fills the gaps

You do not need to keep USER.md meticulously up to date. ScalyClaw learns from every conversation — facts like your name, working hours, preferred language, and current projects are captured automatically by the memory system and included in the dynamic section of the system prompt. USER.md is just the starting point.

How It Works

The buildSystemPrompt() function in scalyclaw/src/prompt/builder.ts assembles the full system prompt on every LLM call. It combines three sources in order:

Disk files — mind/IDENTITY.md, mind/SOUL.md, and mind/USER.md are read from disk and prepended verbatim. These are the only user-editable parts of the prompt.
Code sections — seven hardcoded sections defined in scalyclaw/src/prompt/ are appended next: orchestrator, tools, home, memory, vault, agents, and skills. These sections describe capabilities and constraints that never change; keeping them in code rather than on disk means they cannot be accidentally edited or deleted.
Dynamic data — the current date and time, active channel context, recent memories retrieved via semantic search over the SQLite vector store, resolved secrets from the vault, the full skill manifest, and all agent definitions are injected last.

The mind files sit at position one — they frame everything that follows. The LLM reads your identity and values before it reads anything about tools or capabilities.

typescript

// scalyclaw/src/prompt/builder.ts (simplified)
export async function buildSystemPrompt(ctx: PromptContext): Promise<string> {
  // 1. Disk files — user-editable personality
  const identity = await readMindFile("IDENTITY.md");
  const soul     = await readMindFile("SOUL.md");
  const user     = await readMindFile("USER.md");

  // 2. Code sections — seven hardcoded capability blocks
  const sections = [
    orchestratorSection,
    toolsSection,
    homeSection,
    memorySection,
    vaultSection,
    agentsSection,
    skillsSection,
  ].join("\n\n");

  // 3. Dynamic data — time, memories, tools, agents
  const dynamic = await buildDynamicSection(ctx);

  return [identity, soul, user, sections, dynamic].join("\n\n");
}

Editing

There are two ways to edit the mind files. Direct file edits take effect on the next message automatically. Dashboard edits are saved to disk immediately but require a cache invalidation before they are picked up — run /clear in chat or restart the service.

Dashboard Mind Page

Open the dashboard at http://localhost:3000 and navigate to Mind. The page shows a rich text editor for each of the three files. Changes are saved to disk immediately when you click Save. This is the recommended approach — the editor validates that files are non-empty before saving and shows a diff of what changed. Note that dashboard edits do not automatically invalidate the prompt cache; run /clear in chat to pick up the changes immediately.

Direct File Edit

Edit the files directly in your preferred editor:

bash

# Open all three in your editor
$EDITOR mind/IDENTITY.md mind/SOUL.md mind/USER.md

Direct file edits bypass the cache — buildSystemPrompt() reads from disk on each call, so saving the file is all you need. The next message will use the updated content with no reload step required.

Keep files concise

The LLM reads all three mind files on every single message — they are part of the system prompt that is sent with every API call. Shorter, tighter files mean lower token costs, faster responses, and less noise for the model to reason through. Avoid writing a novel in SOUL.md. A focused paragraph of values outperforms three pages of philosophy every time.