Your CRM in a Folder: The DenchClaw File Structure

DenchClaw stores your entire CRM as files in a folder. Here's a complete breakdown of the file structure — what each file does and how it all fits together.

Kumar Abhirup

March 26, 2026·7 min read

Your CRM in a Folder: The DenchClaw File Structure

One of the most disorienting things about switching to DenchClaw from a SaaS CRM is realizing that your entire business database is just... a folder on your computer.

Open Finder. Navigate to ~/.openclaw-dench/workspace/. Everything is there. Every contact, every deal, every note, every configuration. Files. Your business data as files.

This is deliberate. Local-first architecture means your data is portable, inspectable, versionable, and permanently yours. Let me walk through exactly what's in that folder and what each piece does.

The Top-Level Structure#

~/.openclaw-dench/workspace/
├── workspace.duckdb          ← the database (all CRM data)
├── SOUL.md                   ← agent personality definition
├── USER.md                   ← information about you
├── MEMORY.md                 ← agent's long-term curated memory
├── AGENTS.md                 ← agent behavior rules
├── IDENTITY.md               ← workspace identity
├── TOOLS.md                  ← tool-specific notes
├── HEARTBEAT.md              ← background task checklist (optional)
├── memory/                   ← daily session logs
├── skills/                   ← installed skills (plugins)
├── apps/                     ← custom .dench.app web applications
├── objects/                  ← CRM object YAML configurations
├── docs/                     ← entry-linked markdown documents
├── marketing/                ← workspace-level documents
└── .openclaw/                ← internal runtime files

workspace.duckdb — The Database#

This single file is your entire CRM database. All contacts, companies, deals, activities, tasks — everything structured goes here.

It's a DuckDB database, which means you can open it with:

# DuckDB CLI
duckdb ~/.openclaw-dench/workspace/workspace.duckdb
 
# Python
import duckdb
conn = duckdb.connect("~/.openclaw-dench/workspace/workspace.duckdb")
result = conn.execute("SELECT * FROM v_people LIMIT 10").fetchall()
 
# Any DuckDB-compatible client

The file is typically 10-50MB for a few thousand entries. It compresses well for backup.

Schema overview:

-- Core tables (what DenchClaw manages)
objects       -- table definitions
fields        -- column definitions
entries       -- row metadata
entry_fields  -- actual values
documents     -- markdown doc links
statuses      -- status/pipeline stages
 
-- PIVOT views (auto-generated, human-readable)
v_people      -- flat people table
v_companies   -- flat companies table
v_deals       -- flat deals table
-- ... one v_ view per object

The Agent Identity Files#

These markdown files define who the agent is and what it knows:

SOUL.md: The agent's personality — how it communicates, what it values, what kind of assistant it tries to be. You can edit this to change the agent's communication style.

USER.md: Information about you — your name, timezone, preferences, context. The agent reads this to personalize its responses.

MEMORY.md: The agent's long-term memory. Updated by the agent over time with important facts, decisions, and context worth remembering across sessions. Think of it as the agent's curated mental model of your world.

AGENTS.md: Rules for how the agent should behave — when to speak in group chats, how to handle external actions, safety boundaries. The DenchClaw "constitution."

These files are yours to edit. Change them and the agent's behavior changes accordingly.

memory/ — Daily Logs#

memory/
  2026-03-25.md
  2026-03-26.md
  heartbeat-state.json

The agent writes a daily log file for each active day: what happened, decisions made, context from sessions. These persist across restarts — the agent reads the last few days on startup to rebuild context.

heartbeat-state.json tracks when the agent last checked email, calendar, weather, etc. — used by the background heartbeat system to avoid redundant checks.

objects/ — CRM Schema Configuration#

objects/
  people/
    .object.yaml
  companies/
    .object.yaml
  deals/
    .object.yaml
  tasks/
    .object.yaml

Each directory contains an .object.yaml file that defines the schema and display configuration for that CRM object. This YAML is what drives the frontend UI — field types, view configurations, icons, relationships.

Example .object.yaml:

name: deals
icon: dollar-sign
entry_count: 47
default_view: kanban
 
view_settings:
  kanbanField: "Stage"
 
fields:
  - name: Title
    type: text
    required: true
  - name: Value
    type: number
    format: currency
    currency: USD
  - name: Stage
    type: enum
    options:
      - Prospect
      - Qualified
      - Proposal Sent
      - Negotiating
      - Closed Won
      - Closed Lost
  - name: Contact
    type: relation
    related_object: people
    cardinality: many_to_one
  - name: Company
    type: relation
    related_object: companies
    cardinality: many_to_one
  - name: Close Date
    type: date
  - name: Send Proposal
    type: action
    script: scripts/send-proposal.sh
 
views:
  - name: Active Pipeline
    type: kanban
    filters:
      - field: Stage
        operator: not_in
        value: [Closed Won, Closed Lost]
  - name: Closing This Month
    type: table
    filters:
      - field: Close Date
        operator: this_month
    sort:
      - field: Close Date
        direction: asc

Editing this YAML directly (or via the agent) immediately changes the frontend UI — no restart required.

docs/ — Entry Documents#

docs/
  people/
    sarah-chen-stripe-8f2a3b.md
    john-doe-acme-7e1c9d.md
  deals/
    enterprise-expansion-acme-3f4e2a.md

Each entry can have a linked markdown document. These are the entry's "page" — freeform notes, meeting summaries, proposals, background research.

The filename pattern is {entry-name}-{entry-id}.md. The link between an entry and its document is stored in the documents table in DuckDB.

The agent can write to these documents, read from them, and include them in context when you ask about a specific contact or deal.

skills/ — Plugins#

skills/
  crm/
    SKILL.md
  app-builder/
    SKILL.md
  gstack/
    SKILL.md
    references/
      gstack-spec.md
  browser/
    SKILL.md
  seo/
    SKILL.md
    references/
      keyword-research.md

Each skill is a directory with a SKILL.md file. The skill file teaches the agent how to use a new capability. Skills are just structured markdown — readable, editable, version-controllable.

Community skills from clawhub.ai install into this directory.

apps/ — Custom Web Applications#

apps/
  pipeline-dashboard.dench.app/
    .dench.yaml
    index.html
    styles.css
    charts.js
  deal-calculator.dench.app/
    .dench.yaml
    index.html

Custom applications built with the DenchClaw App Builder. Each app is a self-contained directory ending in .dench.app/. The .dench.yaml manifest defines the app name, icon, permissions, and display settings.

These apps appear in the sidebar and have full access to your DuckDB data via the window.dench bridge API.

.openclaw/ — Runtime Files#

.openclaw/
  web-chat/
    sessions/           ← chat session history (JSON)
  cache/
    browser-snapshots/  ← cached browser screenshots

Internal runtime files managed by OpenClaw. The chat session history in web-chat/sessions/ is especially useful — it contains every conversation you've ever had with the agent, fully searchable.