JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Agent
This guide explains what an Agent is in JiuwenSwarm, how it is structured, where files live on disk, and how to view or adjust configuration safely.
Concepts
What is an agent?
In JiuwenSwarm, an Agent is a digital assistant that can act on its own. It is not just a large language model—it is an execution entity built from several cooperating parts.
Core definition:
Agent = identity + tools + skills + memory + workspace
How it differs from plain LLM chat:
| Aspect | Plain LLM chat | JiuwenSwarm agent |
|---|---|---|
| Execution | Text replies only | Can call tools (files, shell, web search, etc.) |
| Memory | Short-term, within a session | Long-term across sessions; preferences and history |
| Skills | Fixed capability | Loadable skill modules for specialized work |
| Workspace | None | Dedicated workspace for tasks, todos, and state |
| Personalization | None | Identity and config shape tone and behavior |
How the pieces fit together:
┌─────────────────────────────────────────────────────┐
│ Agent │
├─────────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Identity│ │ Tools │ │ Skills │ │ Memory │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Workspace │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│ │
│ │ │ Todo │ │ Config │ │ Sessions ││ │
│ │ └─────────┘ └─────────┘ └─────────────────┘│ │
│ └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
Takeaways:
- Identity — who the agent is and how it communicates
- Tools — “hands” for files, search, code, shell, and media
- Skills — loadable modules (e.g. Git, document workflows)
- Memory — user profile, history, and decisions across sessions
- Workspace — the agent’s “desk” for tasks, config, and sessions
This section is conceptual only. Later sections go into each part in more detail.
Structure
What an agent is made of
An agent has six main areas. You can focus on the ones you care about.
Overview:
| Part | Role | User focus | Main effect |
|---|---|---|---|
| Identity | Who the agent is, tone, style | Customizable | Conversation style and behavior |
| Workspace | Tasks, todos, sessions, runtime data | Good to understand | Task tracking and persistence |
| Tools | Files, web, code, shell, media | Usually no edits | What operations are possible |
| Skills | Professional modules (Git, PPT, etc.) | Load as needed | Extra capabilities |
| Memory | Preferences, history, decisions | Mostly automatic | Continuity and personalization |
| Todo | Task tracking | Day to day | Execution efficiency |
| Config | Models, channels, permissions | Advanced users | Model, security, channel behavior |
Details:
1. Identity
Defines who the agent is and how it talks to you:
- Role (e.g. personal assistant, technical advisor)
- Personality (concise vs. thorough)
- Principles (e.g. try first, then ask; respect trust)
Files: IDENTITY.md, SOUL.md
2. Workspace
Runtime environment for:
- Current tasks and todos
- Session history and state
- Skills and local overrides
- Temporary outputs
Location: under the .jiuwenswarm/ directory
3. Tools
Built-in capabilities, including:
- Files: read, write, edit, search
- Web: search, fetch pages
- Code: Python, JavaScript
- System: shell commands
- Media: image OCR, audio transcription, video analysis
Note: Tools are provided by the system; you normally do not change them manually.
4. Skills
Loadable modules. Each skill typically defines goals, steps, tool usage, and output rules.
Examples:
gitcode-pr— open a Pull Request on GitCodegitcode-pr-review-fix— address PR review comments and update code
Location: skills/ directory
5. Memory
Three kinds:
- User profile — who you are, preferences, habits
- Episodic — events, decisions, conversation snippets
- Semantic — background knowledge and concepts
Note: Memory is mostly automatic; you can search history when needed.
6. Config
Controls runtime behavior:
- Model choice and parameters (temperature, timeout, etc.)
- Channels (Feishu, WeChat, Telegram, etc.)
- Permissions (what needs your approval)
- Memory and logging
File: config/config.yaml
You do not need to edit everything by hand. In practice, focus on identity and skills; the rest is largely managed by the system.
Directory layout
Local paths and key files
High-level layout under your user data directory:
Overview:
C:\Users\<username>\.jiuwenswarm\
│
├── config/ # Configuration
│ ├── config.yaml # Main config (models, channels, permissions)
│ └── builtin_rules.yaml # Built-in rules
│
├── agent/ # Agent-related data
│ └── <service_id>/ # Service instance
│ └── <agent_id>/ # Agent instance
│ ├── agent/ # Agent workspace
│ │ ├── AGENT.md # Agent bootstrap config
│ │ ├── IDENTITY.md # Identity
│ │ ├── SOUL.md # Values and persona
│ │ ├── HEARTBEAT.md # Heartbeat tasks
│ │ └── sessions/ # Session data
│ ├── config/ # Per-agent config overrides (optional)
│ ├── memory/ # Agent memory store
│ ├── skills/ # Skills
│ └── todo/ # Todos
│
├── gateway/ # Gateway data
├── logs/ # Log files
├── memory/ # Global memory store
├── received_files/ # Incoming external files
└── web/ # Web channel assets
Key files:
| Path | Purpose | Edit? | If you change it |
|---|---|---|---|
config/config.yaml |
Models, channels, permissions, memory | Advanced users, carefully | Affects models, channels, security; restart required |
config/builtin_rules.yaml |
Built-in rules | Not recommended | Changes default system behavior |
agent/<id>/agent/AGENT.md |
Bootstrap config | Yes, when needed | Affects startup behavior |
agent/<id>/agent/IDENTITY.md |
Identity | Customizable | Affects how the agent sees its role |
agent/<id>/agent/SOUL.md |
Values and persona | Customizable | Affects tone and style |
agent/<id>/agent/HEARTBEAT.md |
Heartbeat tasks | Adjustable | Affects scheduled / proactive behavior |
agent/<id>/skills/ |
Skills | Add skills | Extends capabilities |
agent/<id>/memory/ |
Memory store | Do not edit by hand | Risk of corrupting memory data |
agent/<id>/todo/ |
Todos | System-managed | Affects task tracking |
logs/ |
Logs | View only | Used for troubleshooting |
Example (Windows):
C:\Users\Administrator\.jiuwenswarm\
├── config\config.yaml
├── service_default_service_id\
│ └── agent_default_agent_id\
│ └── agent\
│ ├── AGENT.md
│ ├── IDENTITY.md
│ ├── SOUL.md
│ ├── skills\
│ └── sessions\
Notes:
- Restart the service after changing config files.
- Do not hand-edit memory or session stores unless you know what you are doing.
- New skills must follow the skill format (see Skills).
Operations
Viewing and understanding agent configuration
How to inspect settings and what is safe to change.
View configuration
Option 1: Ask the agent
Examples:
- “Show me the current configuration.”
- “Where is my agent config file?”
- “Read config.yaml for me.”
The agent can read and summarize the files.
Option 2: Open the file directly
Use an editor (VS Code, Notepad++, etc.):
C:\Users\<username>\.jiuwenswarm\config\config.yaml
Risk levels
Category 1 — safe to read
| Key | Meaning | Suggestion |
|---|---|---|
preferred_language |
Preferred language | Read-only OK |
logging.level |
Log level | Read-only OK |
heartbeat.every |
Heartbeat interval | Read-only OK |
channels.*.enabled |
Channel on/off | Read-only OK |
Category 2 — change with care
| Key | Meaning | Effect | Suggestion |
|---|---|---|---|
models.default.model_name |
Default model | Quality and speed | Confirm the model works first |
models.default.temperature |
Temperature | Creativity vs. stability | Often 0.7–1.0 |
heartbeat.active_hours |
Active window | When proactive runs fire | Match your schedule |
permissions.tools.* |
Tool permissions | Safety | Understand risk before changing |
Category 3 — avoid unless you know why
| Key | Meaning | Risk | Suggestion |
|---|---|---|---|
models.default.api_key |
API key | Leakage | Prefer environment variables |
memory.external.* |
External memory engine | Memory may break | Keep defaults |
gateway.* |
Gateway settings | Connectivity | Change only when deploying |
permissions.rules.* |
Security rules | Security holes | Keep defaults |
After you change config
Restart is required for changes to take effect.
# Windows (depends on how you installed)
# If running as a service:
net stop jiuwenswarm
net start jiuwenswarm
# If running from the command line:
# Stop the current process, then:
jiuwenswarm-start
# or: python -m jiuwenswarm.app
Common scenarios
Scenario 1: Switch model
# In config.yaml
models:
default:
model_client_config:
model_name: "your-model-name" # e.g. deepseek-chat, gpt-4o
Restart the service.
Scenario 2: Adjust reply style
models:
default:
model_config_obj:
temperature: 0.8 # more creative
# temperature: 0.3 # more stable
Scenario 3: Enable or disable a channel
channels:
feishu:
enabled: true
telegram:
enabled: false
Troubleshooting
If something breaks after a config change:
- Check logs under
logs/ - Revert the changed values
- Restart the service
- Ask the agent to help interpret errors
Safety:
- Back up
config.yamlbefore editing.- When unsure, ask the agent first.
- Put API keys in environment variables (
.env), not plain text in YAML when possible.
Simplified Chinese: 智能体