Workspace Files

Overview

oxicrab stores all its state in a home directory, defaulting to ~/.oxicrab/. The workspace is a subdirectory that holds the markdown files that define the agent's identity, memory, and context. These files are loaded into the system prompt on every conversation.

Run oxicrab onboard to scaffold the full directory structure with templates.

AGENTS.md template

How it's used

Loaded as the core identity section of the system prompt. Unlike other bootstrap files, AGENTS.md is loaded separately and placed first, before USER.md or TOOLS.md. If the file is missing, oxicrab falls back to a built-in default identity.

Recommended sections

• Personality — Tone and communication style (e.g. "friendly but professional", "concise")
• Capabilities — Brief overview of what the agent can do (no need to list every tool)
• Behavioral Rules — Constraints like "never guess information", "ask for clarification when ambiguous"
• Action Integrity — Rules about never claiming to have done something without actually calling a tool
• Memory Management — How aggressively the agent should write to memory
• Learned Adaptations — A section the agent updates itself as it learns user preferences

Example

# mybot

I am mybot, a personal AI assistant.

## Personality

- Friendly but professional
- Direct and concise, with detail when needed
- Accuracy over speed

## Capabilities

I have access to tools including file operations, web search,
shell commands, messaging, and more. Some tools require
additional configuration.

## Behavioral Rules

- Reply directly to questions. Only use the message tool
  when sending to a specific chat channel.
- Never invent or guess information.
- Ask for clarification when ambiguous.

## Learned Adaptations

*(Updated automatically as I learn preferences)*

USER.md template

How it's used

Loaded as a bootstrap file in the system prompt, after AGENTS.md. This gives the agent persistent context about who it's talking to across all sessions.

Example

# User

## Preferences

- Communication style: casual
- Timezone: America/New_York
- Language: English

## Notes

- Prefers metric units
- Works primarily with Python and Rust

TOOLS.md template

How it's used

Loaded as a bootstrap file alongside USER.md. Helps the agent understand what tools are available and any special instructions for using them.

Example

# Tool Notes

## Configured Tools

- Google Mail and Calendar are connected (OAuth)
- Weather uses metric units, default location: London
- Todoist is set up for personal project tracking

## API Keys & Services

- Brave Search: configured
- OpenWeatherMap: configured
- GitHub: configured via PAT

MEMORY.md manual + agent

How it's used

Always included in the memory context section of the system prompt. Also indexed by the full-text search database for the memory_search tool.

What to put here

• Important facts the agent should always know
• User preferences discovered over time
• Project context, account details (no secrets)
• Corrections to previous misunderstandings

Daily Notes automatic

How it's used

Today's note is included in the system prompt for session continuity. All daily notes are indexed by the full-text search database. Older notes are managed by the memory hygiene system.

Lifecycle

• Created — Automatically on first write each day (UTC date)
• Indexed — Background indexer runs every 5 minutes (configurable via memoryIndexerInterval)
• Archived — Moved to memory/archive/ after archiveAfterDays (default: 30)
• Purged — Deleted after purgeAfterDays (default: 90)

Memory search

The memory_search tool queries a SQLite FTS5 database (memory.sqlite3) that indexes all memory files. If embeddings are enabled, it uses hybrid vector + keyword search for better relevance.

Configuration

{
  "agents": {
    "defaults": {
      "memoryIndexerInterval": 300,
      "memory": {
        "archiveAfterDays": 30,
        "purgeAfterDays": 90,
        "embeddingsEnabled": false,
        "embeddingsModel": "BAAI/bge-small-en-v1.5",
        "hybridWeight": 0.5
      }
    }
  }
}

Skills manual

How it's used

Skills marked always: true are included in every system prompt. Other skills appear as a summary, and the agent loads the full content on-demand using the read_file tool when relevant.

SKILL.md format

---
name: my-skill
description: What this skill does
always: false
requires:
  bins: ["ffmpeg", "curl"]
  env: ["MY_API_KEY"]
---

# My Skill

Instructions for the agent on how to use this skill.

## When to use

Describe the situations where this skill applies.

## Steps

1. Step one
2. Step two

Frontmatter fields

• name — Skill identifier (matches directory name)
• description — One-line summary shown in the skills list
• always — If true, full content is included in every prompt (default: false)
• requires.bins — CLI tools that must be installed (checked at runtime)
• requires.env — Environment variables that must be set

Sessions

How it's used

The agent loads the most recent messages from the session file to maintain conversation continuity. An LRU cache of 64 sessions is kept in memory for performance.

Lifecycle

• Auto-pruned to the 200 most recent messages
• Expired after sessionTtlDays (default: 30 days)
• Compaction available to summarize long conversations (configurable via compaction settings)

Other Files

These files live in the oxicrab home directory (~/.oxicrab/) rather than the workspace.