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.
Session
Sessions are the core mechanism in JiuwenSwarm for managing conversation history and context.
Concepts
What is a Session
A Session is a data unit in JiuwenSwarm used to record and manage single or multiple continuous conversation interactions. Each session contains:
- Conversation History: Complete message exchanges between user and AI
- Context Information: Current task status, execution progress, intermediate results, etc.
- Metadata: Session ID, creation time, last update time, and other identifiers
Tip: Session and Memory are two different concepts:
- Session: Temporary conversation history, disappears when closed or cleared
- Memory: Persistently stored important information, retained across sessions
Session File Structure
JiuwenSwarm session data is stored in the local workspace with the following structure:
.jiuwenswarm/
└── agent/
└── sessions/
├── sess_19ddd41cbc0_fd1e4d/ # Regular session directory
│ ├── metadata.json # Session metadata
│ └── history.json # Conversation history
├── sess_19ddd5cc729_09bb02/ # Another session
│ ├── metadata.json
│ └── history.json
├── heartbeat_19de6f526fb_224694/ # Heartbeat session directory
│ ├── metadata.json
│ └── history.json
└── ...
Session Types:
| Directory Prefix | Type | Description |
|---|---|---|
sess_ |
Regular Session | Conversation sessions initiated via Web, Feishu, etc. |
heartbeat_ |
Heartbeat Session | System heartbeat task sessions |
cron_ |
Cron Session | Scheduled task sessions (cron_id is non-empty in metadata.json) |
Session type distinction:
- Regular sessions:
cron_idis empty; retrieved viaproject.get_sessions - Cron sessions:
cron_idis non-empty (set to theCronJob.id); retrieved viaproject.get_cron_sessions, supports filtering bycron_idfor all historical runs of a task - The two types are mutually exclusive in project view;
project.listsession_countonly counts regular sessions
metadata.json File Content:

| Field | Description | Example |
|---|---|---|
session_id |
Unique session identifier | sess_19ddd41cbc0_fd1e4d |
channel_id |
Session source channel | web, feishu, __heartbeat__ |
user_id |
User identifier | Empty or user ID |
created_at |
Session creation time (Unix timestamp) | 1716249600.732591 |
last_message_at |
Last message time | 1716253200.865117 |
title |
Session title (usually first message summary) | Help me write a technical document |
message_count |
Total message count | 15 |
mode |
Execution mode | agent.plan |
project_id |
Project ID the session belongs to | proj_abc123 (empty string = default project) |
cron_id |
Source cron job ID | Empty for regular sessions; non-empty for cron-triggered sessions |
history.json File Content:
history.json is a JSON array that records complete conversation history. Each message contains the following fields:

| Field | Description | Example |
|---|---|---|
id |
Unique message identifier, suffix user indicates user query, suffix assistant indicates agent response |
req_mol5noj7_22:user |
role |
Message role | user or assistant |
request_id |
Request identifier | req_mol5noj7_22 |
channel_id |
Message source channel | web |
timestamp |
Message timestamp | 1777533730.7309785 |
content |
Message content | User input or AI response text |
event_type |
Event type | chat.delta, chat.final, chat.reasoning |
tool_calls |
Tool call information (only in assistant messages) | Contains tool name, parameters, etc. |
Tip: Agent response messages also contain
tool_callsand other fields for recording tool call information.
Why Sessions are Needed
The session mechanism plays an important role in JiuwenSwarm:
Context Continuity
- Maintains conversation coherence, AI can understand previous exchanges
- Supports information reference and supplementation in multi-turn conversations
Task State Tracking
- Records task planning, execution progress, and intermediate results
- Supports task interruption, resumption, and adjustment
History Review
- Users can view previous conversation records
- Facilitates review and problem-solving process tracing
Resource Management
- Reasonably manages conversation context, avoids information overload
- Supports context compression mechanism, optimizes token usage
Session Use Cases
| Scenario | Description |
|---|---|
| Daily Conversation | Q&A, consultation, content creation with AI |
| Task Execution | Execute complex tasks, track progress, adjust plans |
| History Review | View previous conversations, resume interrupted work |
| Problem Investigation | Trace issues through session records, analyze execution process |
| Multi-task Switching | Switch between different sessions, handle multiple independent tasks |
| Cron Task Execution | Scheduled tasks automatically trigger sessions, execute periodic work |
| Multi-channel Conversation | Conversations from different channels (Web, Feishu, WeChat, etc.) |
Feature Demo
View Session Chat History
You can view complete chat history of all sessions to understand past conversation content.

Steps:
Via Web Interface
- In JiuwenSwarm Web interface, click "Sessions" in the left navigation
- Enter session management page to see all session list (as displayed in frontend session management)
- Click any session to view its complete chat history
Via Local Files
- Navigate to session storage directory:
.jiuwenswarm/agent/sessions/ - Enter the corresponding session directory (e.g.,
sess_19ddd41cbc0_fd1e4d/) - View conversation content in
history.jsonfile
- Navigate to session storage directory:
Tip: The frontend page has a "Conversation Preview" toggle to switch between JSON text format or conversation page format, convenient for viewing raw data or conversation content.
Restore Session
Restoring a session syncs historical session content to the frontend to continue previous work.


Steps:
- Find the session to restore in the session management page (recommend selecting an actual chat history session, not a heartbeat session)
- Click the "Restore" button or double-click the session entry
- System will load all historical messages for that session
- After restoration, you can see complete conversation history in the chat page
- Continue entering new content, AI will respond based on historical context
Use Cases:
| Scenario | Description |
|---|---|
| Interruption Recovery | Previous work was interrupted, need to continue |
| Task Continuation | Complex task completed in multiple sessions, continue from last progress |
| Content Supplement | Not satisfied with previous results, need to add requirements or adjust |
Notes:
- After restoring a session, new messages will be appended to the original history
- If the session contains incomplete tasks, the system will attempt to restore task state
- Long inactive sessions may have been compressed and need decompression when restored
Delete Historical Session
If a session is no longer needed, you can delete it directly in session management to free storage and keep the list tidy.

Steps:
- In JiuwenSwarm Web interface, click "Sessions" in the left navigation
- Select the session to delete in the session management page
- Click the delete icon in the right-side session detail area
- In the popup confirmation dialog, click "Confirm"
- After successful deletion, the session will be removed from the list
Tip: Please make sure the selected session is no longer needed. Deleted sessions may not be recoverable.
FAQ
Q1: What's the difference between session and memory?
Session is temporary conversation history, storing all messages during the current conversation, disappears when cleared or closed. Memory is persistently stored important information like user preferences, key knowledge points, retained across sessions.
Q2: How much storage space do sessions use?
Session data is usually small, each message is about a few KB. But if containing many file uploads or long conversations, a single session can reach several MB. It's recommended to periodically clean up unneeded historical sessions.
Q3: Will previous task state be preserved after restoring a session?
Yes, when restoring a session, the system will attempt to restore previous task state including task list, execution progress, etc. However, some tasks that were being executed may need to be re-triggered.
Q4: Where is session data stored?
Session data is stored in the .jiuwenswarm/agent/sessions/ directory of the local workspace. Each session is an independent directory containing metadata.json and history.json files.
Q5: How to backup important sessions?
You can:
- Directly copy session JSON files to another location
- Export session content as Markdown or text format
- Write important information to memory for cross-session retention
Related Links
- Quick Start - Learn JiuwenSwarm basics
- Memory System - Learn about persistent memory mechanism
- Task Planning - Learn about task management mechanism
- Page Overview - Learn about interface layout
- Agent Tutorial - Learn about conversation features
Document Version: v1.0
Target Audience: JiuwenSwarm Users
Last Updated: 2026-05-05