Agent & workspace

workspace is JiuwenSwarm’s runtime directory for agent memory, skills, session data, and configurable heartbeat tasks. In source mode it lives at the project root workspace; in wheel install mode, the bundled workspace is copied to ~/.jiuwenswarm/workspace on first run.

Layout overview

The installed user workspace layout (~/.jiuwenswarm/workspace/):

workspace/
├── agent-data.json        # Agent list metadata (generated by scripts/generate-agent-folders.js)
├── skills_state.json      # Skill install/market state (generated)
├── AGENT.md               # Agent identity (from AGENT_ZH.md or AGENT_EN.md at init)
├── HEARTBEAT.md          # Heartbeat tasks (from HEARTBEAT_ZH.md or HEARTBEAT_EN.md at init)
├── IDENTITY.md           # Identity (from IDENTITY_ZH.md or IDENTITY_EN.md at init)
├── SOUL.md               # Persona for system prompts (from SOUL_ZH.md or SOUL_EN.md at init)
├── USER.md               # User profile (created by user/agent)
├── MEMORY.md             # Long-term memory (from MEMORY_ZH.md or MEMORY_EN.md at init)
├── memory/               # Memory system
│   ├── YYYY-MM-DD.md     # Daily memory (generated)
│   ├── messages.json     # Compressed message store (generated)
│   └── memory.db          # ChromaDB vector store (generated)
├── skills/               # Marketplace/installed skills
│   ├── _marketplace/     # Marketplace clone cache
│   └── <skill-name>/     # Per-skill directory
└── session/              # Sessions (generated)
    ├── sess_<id>/         # Normal sessions
    │   ├── todo.md        # Todo list (TodoToolkit)
    │   └── *.md, *.json   # Session outputs
    └── heartbeat_<id>/    # Heartbeat sessions

The package template for built-in skills lives at jiuwenswarm/resources/agent/workspace/skills/. These are not copied to the user workspace on init (they are loaded directly from the package in source mode, or from ~/.jiuwenswarm/workspace/skills/ if explicitly installed).

---

Pre-configured content

Shipped with the package or source; you can use or edit as needed:

Path (in workspace)	Description
HEARTBEAT.md	Heartbeat template (jiuwenswarm/resources/agent/workspace/HEARTBEAT_ZH.md or HEARTBEAT_EN.md, copied by language at init). If present and valid, the agent reads it on each heartbeat; otherwise only HEARTBEAT_OK is returned. Editable in the web UI.
SOUL.md	Persona for system prompts.
skills/	Marketplace/installed skills. Each skill has SKILL.md, prompts/, references/, etc.
skills/_marketplace/	Marketplace clone cache; empty by default.
memory/	Memory layout. USER.md and MEMORY.md may be created on first use.

---

Dynamically generated content

Created or updated at runtime:

Path (in workspace)	Description
agent-data.json	Generated by scripts/generate-agent-folders.js for the web UI.
skills_state.json	Maintained by SkillManager for installed marketplace plugins.
memory/YYYY-MM-DD.md	Daily memory files.
memory/messages.json	Compressed messages for memory.
memory/memory.db	ChromaDB for memory_search.
skills/<skill>/evolutions.json	Skill evolution records.
session/<session_id>/	One folder per session.
session/<session_id>/todo.md	Todo list for that session.
session/<session_id>/*	Other session artifacts.

---

Related configuration

• Skill root: skill_base_dir in config/config.yaml, default agent/skills.
• Memory workspace: ~/.jiuwenswarm/workspace/ (get_agent_workspace_dir()).
• Sessions: ~/.jiuwenswarm/workspace/session/, one subfolder per session_id.
• SkillNet usage in Swarm: see Skills.md §5.