Agent folder layout

A mono-agent lives in one folder. You edit its config and context files; the framework writes runtime state under .mono-agent/. In normal CLI use, relative config paths resolve from this folder. Only fields with a documented MONO_AGENT_* mapping accept an environment override.

The tree

my-agent/
  mono-agent.config.json   # the single agent declaration (runtime, channels, memory, tools...)
  IDENTITY.md              # role, boundaries, references to existing knowledge (required)
  SOUL.md                  # optional: voice/persona/values layered on top of IDENTITY
  skills/                  # optional: <skill-name>/SKILL.md per selected skill
  cron/                    # optional: <job-id>.md scheduled prompts (frontmatter + body)
  webhook/                 # optional: <name>.md per-endpoint webhook prompts (frontmatter + body)
  mcp.json                 # optional: MCP server definitions
  .env                     # optional: secrets; auto-loaded by the CLI, never committed
  .mono-agent/             # framework-managed runtime state (gitignore this)
    artifacts/             # JSONL run summaries + events (local traceability fallback)
    workspace/             # runtime working directory (when not ".")
    memory/                # built-in memory root (framework-managed)
      daily/               # canonical dated memory notes
      graph.jsonl          # BuJo canonical entity graph
      .replay-projection-v1.json # BuJo exact metadata-only replay authority (0600)
      .index/              # managed generations, manifest, runtime snapshot
      .capture-intake/     # owner-only durable completed-turn intake
    whatsapp-auth/         # Baileys auth state (WhatsApp channel only)
    sessions/              # optional durable Pi sessions when piSessionsRoot is set
    process-jobs/          # opt-in owner-private Exec/Bash job records and output
    process-jobs-roots-v1/ # monotonic retained-root protection registry
    process-jobs-roots-v1.recovery/ # bounded locked registry recovery artifacts; empty at rest
    acp-sessions/          # owner-only ACP session authorization records
    trace-sources/         # traceability registry (when kept folder-local)

Only runtime.model and context.identityPath are required. Most other capabilities are opt-in, but the loopback tui operator endpoint defaults on. Scaffold a folder with mono-agent init, then check it with mono-agent validate; see the CLI reference.

Author-edited files

These are the inputs you write by hand (or let an agent edit). They are the source of truth and belong in version control.

Path	Holds	Config key	Coverage
mono-agent.config.json	The entire agent declaration — runtime, channels, memory, tools, observability.	(the file itself)	config
IDENTITY.md	The agent’s role, boundaries, and pointers to existing knowledge. Required.	context.identityPath	config
SOUL.md	Optional voice/persona/values layer assembled on top of identity.	context.soulPath	config
skills/<name>/SKILL.md	One folder per selected skill; each SKILL.md is progressively disclosed at runtime.	context.skillsRoot / context.selectedSkills	config
skills/.mono-agent-managed.json	Version/hash ledger for the two project skills generated by init.	mono-agent install-skill --project --check|--update	cli
cron/<id>.md	A scheduled prompt: YAML frontmatter (schedule, timezone) plus the prompt body.	cron.dir (default cron)	config
webhook/<name>.md	A per-endpoint webhook prompt prepended to incoming request text: frontmatter plus body.	webhook	config
mcp.json	External MCP server definitions, referenced from the config.	tools.mcpConfigPath	config
.env	Secrets and optional overrides loaded by agent-aware CLI commands.	environment layer	config

For what goes inside each, see Identity & soul, Skills, Cron, Webhook, and MCP.

Caution

Never commit .env. Exported shell variables win over it, and --env-file <path> selects another file. Guided init preserves existing non-empty assignments and comments, writes automatically only when it can prove an owner-only safe POSIX path, and otherwise gives manual instructions. Never copy .env.example over a populated .env. See CLI reference → Secret persistence.

Consumer docs consistency

When a downstream consumer folder lives outside this repo, run the manual docs/config drift gate against explicit local paths:

node scripts/check-consumer-docs-consistency.mjs \
  --consumer /Users/example/local-agent-alpha \
  --consumer /Users/example/local-agent-betas/orchestrator

The check is static and offline. It compares each consumer README.md with that same folder’s mono-agent.config.json and configured MCP file, then fails stale references to retired surfaces such as @mono-agent/memory-mcp, memory_note, and the operator console when the local config no longer exposes them.

The .mono-agent/ runtime directory

The framework creates and writes everything under .mono-agent/. You generally do not edit these files; add the whole directory to .gitignore.

Path	Holds	Config key
.mono-agent/artifacts/	JSONL run summaries and events — the completed-run record after terminal persistence. start() independently replaces empty events plus a running summary, later events buffer in RAM, and terminal files are independently replaced; a crash can lose buffered data, and stale reconciliation sees only persisted data.	artifacts.dir
.mono-agent/history/	Bounded canonical conversation state. Top-level *.history.json files keep 64 messages per exact conversation id; tool-history/tool-lifecycles.sqlite independently keeps redacted/bounded managed-tool lifecycles, and .locks/tool-lifecycles-owner.sqlite enforces one writer. All survive ordinary restarts independently of warm-session mode.	automatic; stored beside artifacts.dir
.mono-agent/workspace/	The runtime working directory, when runtime.workspace is not ".".	runtime.workspace
.mono-agent/memory/	Built-in memory root: canonical daily notes, BuJo graph.jsonl and owner-only .replay-projection-v1.json, durable intake, and the managed .index/. The replay sidecar is exact metadata-only authority for BuJo lifecycle/thread replay; do not edit it or SQLite directly.	memory.path
.mono-agent/whatsapp-auth/	Baileys auth state, written only when the WhatsApp channel is enabled.	(WhatsApp channel)
.mono-agent/sessions/	Optional Pi-native provider transcripts used with canonical history for cross-restart resume. Without piSessionsRoot, provider sessions are process-local.	providers.piNative.piSessionsRoot
.mono-agent/process-jobs/	Opt-in owner-private Pi-native Exec/Bash records plus bounded stdout/stderr artifacts. Records survive ordinary restart and --clear-sessions; jobs themselves are interrupted at restart.	processJobs.stateDir
.mono-agent/process-jobs-roots-v1/	Bounded monotonic registry of every process-job state root ever enabled for this agent. It survives disable, removal, state-root changes, and restart so dormant roots remain protected.	automatic; absent until the first registration
.mono-agent/process-jobs-roots-v1.recovery/	Owner-only, same-filesystem recovery namespace for the root registry. It permits only the three fixed staging/previous/failed manifest names, is inspected read-only by requests, and is repaired only under the registry mutation lock; it is empty in steady state.	automatic; created by registry mutation
.mono-agent/acp-sessions/	Owner-only, hashed authorization records for durable ACP session resume. These bind opaque ids to one source and workspace; prompt content and credentials are not stored here.	automatic; stored beside artifacts.dir
.mono-agent/trace-sources/	The traceability registry, when kept folder-local.	traceability.registryDir

Note

mono-agent restart --clear-sessions purges persisted Pi sessions/, top-level message history, the tool-lifecycle sidecar, and acp-sessions/ authorizations for a fresh start. Its output reports message-history bytes separately from tool-history files/bytes and record counts (or says when counts were unreadable). It keeps durable memory, recorded run artifacts, every registered process-job root, and the retained-root registry plus its recovery directory. Preflight recovers, freezes, and validates that registry under its mutation lock and refuses an overlap before deleting anything. Any nonterminal process job is interrupted by restart independently of this flag. See Sessions & concurrency, Background process jobs, Artifacts & traces, and Capture & recall.

Applying changes

Edit mono-agent.config.json or its referenced markdown directly. The CLI does not watch those files, so run mono-agent restart to apply an edit. A programmatic host may call app.applyConfigChange(reason) explicitly. start prints the traceability source and each channel’s initial state (running, waiting_for_config, disabled, or failed); a self-recovering running transport can later report degraded.

See the config blueprint for a broad example, environment variables for overrides, and programmatic composition for behavior that JSON cannot express.