AgentFS Filesystem
v10.0.179+ (standing instructions in instructions.md).
AgentFS is Like Each Agent's "Home"
If DesireCore is like a community, then AgentFS is each agent's "home" in that community. This home contains its personal profile, work manual, skill certificates, memory logs, and archived receipts from every job.
You might ask: why not use a database to store all this?
The answer is simple: files are the most transparent form of data. You can directly open files to see everything about the agent — its personality, the rules it learned, the things it remembers. No SQL queries needed, no specialized database management tools.
Design Inspiration
AgentFS's design is inspired by the Linux operating system's file structure:
| Linux Filesystem | AgentFS | Analogy |
|---|---|---|
/usr/share/app/ | agents/<id>/ | Application core, shareable |
/home/user/ | users/<user_id>/ | User private data |
/var/run/ | runs/ | Runtime temporary files |
/var/cache/ | cache/ | Rebuildable cache |
/var/log/ | logs/ | Log records |
Overall Directory Structure
~/.desirecore/
├── config/ # Global configuration (your personal settings)
│
├── agents/ # All agents' "homes"
│ └── <agent_id>/
│ ├── agent.json # ID card: basic info and configuration
│ ├── persona.md # Personality profile: communication style, decision preferences
│ ├── principles.md # Behavioral guidelines: rules, forbidden zones, baselines
│ ├── instructions.md # Optional standing responsibilities, strategies, and delivery standards
│ ├── memory/ # Memory bank: facts and experiences it remembers
│ ├── skills/ # Skill packages: various skills it has learned
│ ├── workflows/ # Workflows: execution plans for complex tasks
│ ├── tools/ # Toolbox: external tools it can use
│ ├── heartbeat/ # Heartbeat: content it actively monitors
│ ├── resources/ # Reference materials: documents, knowledge bases
│ ├── assets/ # Static resources: images, templates
│ └── .git/ # Version control
│
├── users/ # User-specific data
│ └── <user_id>/
│ ├── profile.md # Your personal profile
│ ├── preferences.md # Your preference settings
│ └── agents/ # Your "relationship" with each agent
│ └── <agent_id>/
│ ├── relationship.md # Interaction records and relationship
│ ├── memory/ # Exclusive memories with this agent
│ └── preferences/ # Your exclusive settings for this agent
│
├── runs/ # Execution records (temporary)
├── cache/ # Cache (rebuildable)
└── logs/ # Logs
Core Directory Analysis
agents/ — Agent Core
This is where the agent's "soul" resides. Each agent is a Git repository containing:
| File/Directory | Purpose | Analogy |
|---|---|---|
agent.json | Agent's basic info, version number | ID card |
persona.md | Personality, tone, decision preferences | Character traits |
principles.md | Behavioral guidelines, red lines, baselines | Professional ethics |
instructions.md | Optional stable responsibilities, work strategies, and delivery standards | Working agreement |
memory/ | Accumulated knowledge and experience | Long-term memory |
skills/ | Various learned skills | Skill certificates |
tools/ | External tools it can use | Toolbox |
users/ — User Private Data
Your personal data is stored completely independently, strictly isolated from the agent core. Even if you use the same agent, your data won't be mixed with others.
runs/ — Execution Records
Detailed process of each task execution, including receipts, session records, etc. This is the data source for "post-hoc auditing."
Why Filesystem Instead of Database
| Feature | Filesystem | Database |
|---|---|---|
| Transparency | Open files directly to view | Requires query tools |
| Version Control | Native Git support | Requires additional solution |
| Portability | Copy folder to migrate | Requires export/import |
| Auditability | Every modification has Git record | Requires audit logs |
| AI-Friendly | AI reads/writes files directly | Requires API adaptation |
| Offline Available | Local files always available | May depend on services |
Benefits of File-Driven Architecture
1. Agents Can "Modify Themselves"
Because everything is files, agents can directly read and write their own files to learn and evolve. For example, behavioral boundaries belong in principles.md, agent-specific stable responsibilities in instructions.md, and detailed methods in skills. Personal preferences stay in the user scope. This is much simpler than operating a database through APIs.
2. Humans Can Easily Review
All changes are file diffs. You can review the agent's every "learning outcome" like reviewing code. What was deleted, what was added — clear at a glance.
3. Distributable Like Software
The agent core is a Git repository — can be cloned, forked, published to marketplace. The agent you cultivated well can be shared with others.
4. Natural Rollback Support
Made a mistake? git revert and it's back. Not satisfied with recent "evolution"? Roll back to the previous version.
Tiered Loading
Persona, principles, and layered global or team prompts can use L0/L1/L2 to control loading granularity. Skills also support on-demand discovery. Not every AgentFS file uses these tiers:
| Tier | Content | Consumption | Purpose |
|---|---|---|---|
| L0 | One-sentence summary | Minimal | Quick filtering, routing |
| L1 | Core info + applicable scenarios | Low | Planning and decision-making |
| L2 | Complete content | On-demand | Actual execution |
instructions.md uses ordinary Markdown without L0/L1/L2 parsing. When allowed, it loads in full without summarization or truncation; detailed procedures belong in skills. See the standing instructions format for content ownership and update behavior.
Next Steps
- Want to understand the various memory types of agents? Go to the Memory System chapter in the User Guide
- Want to understand specific file formats? Read File Format Reference
- Want to understand where data is stored? Read Data Storage Locations