Files

T

darman 9929941748 Add project documentation and reference materials

Include Luna AI Assistant design docs covering channels, configuration,
core architecture, memory, scheduler, and skills. Add reference docs
from OpenClaw and ZeroClaw projects, plus Mistral and OpenAI API specs.

2026-04-04 04:14:06 +02:00

4.2 KiB

Raw Blame History

Sessions

ZeroClaw implements a robust session management system designed for multi-user environments and crash resilience. Unlike simple stateless request-response loops, ZeroClaw treats every interaction as part of a persistent, per-sender conversation that survives process restarts and handles context growth through automated compaction.

Per-Sender Storage

Each conversation is isolated and keyed by a combination of the sender ID and the communication channel. This ensures that users on different platforms (e.g., Discord vs. Slack) or multiple users within the same platform maintain independent histories.

Session Keying: Sessions are typically indexed by (channel_id, sender_id).
Isolation: Memory and history from one sender never bleed into another's session unless explicitly shared via global memory.
Persistence: Sessions are serialized and stored as JSON files, allowing the agent to resume exactly where it left off after a restart.

Compaction Logic

To prevent context window overflow and maintain performance over long conversations, ZeroClaw uses an automated compaction mechanism defined in agent/loop_.rs. When the history grows beyond a specific threshold, old messages are summarized and replaced by a concise context block.

Threshold: Compaction triggers when the non-system message count exceeds DEFAULT_MAX_HISTORY_MESSAGES = 50.
Retention: ZeroClaw keeps the COMPACTION_KEEP_RECENT_MESSAGES = 20 most recent messages in their original form.
Source Cap: The transcript passed to the summarizer is limited to COMPACTION_MAX_SOURCE_CHARS = 12_000 to avoid overwhelming the summarization model.
Summary Cap: The resulting summary is truncated to COMPACTION_MAX_SUMMARY_CHARS = 2_000.

The summarization process is handled by a recursive call to the provider, instructing it to preserve key facts, user preferences, and unresolved tasks while omitting filler and verbose tool logs.

Autosave Thresholds

ZeroClaw prioritizes data integrity through aggressive autosaving. Sessions are not just saved on graceful shutdown; they are updated after every significant interaction.

Trigger: AUTOSAVE_MIN_MESSAGE_CHARS = 20.
Behavior: If a user message exceeds this length, it is considered "meaningful" enough to trigger an immediate save of the session state.
Crash Resilience: This granular saving ensures that even in the event of a sudden crash or hardware failure, the agent loses at most the very last exchange.

Per-Sender Overrides

Each session can carry its own configuration, allowing for dynamic behavior based on the specific user or channel requirements.

Model Overrides: A specific conversation can be configured to use a different provider or model than the global default.
Config Storage: These overrides are stored alongside the session JSON, ensuring consistency across restarts.

Session Lifecycle

Creation: A new session is initialized when a message is received from a previously unknown (channel, sender) pair.
Loading: Upon receiving a message, ZeroClaw checks the local storage for an existing session file matching the sender's key.
Processing: Messages are appended to the history, and compaction is checked before sending the request to the LLM.
Saving: The session is written to disk after the LLM responds or when the autosave threshold is met.
Cleanup: Older sessions can be archived or deleted based on global retention policies, though ZeroClaw typically favors long-term persistence.

Relevance to Luna

Luna's SessionManager currently implements basic compaction via the LibrarianAgent, but lacks several of ZeroClaw's more robust features. Integrating these would significantly improve reliability and flexibility:

Autosave: Implementing the AUTOSAVE_MIN_MESSAGE_CHARS logic to move away from shutdown-only saves. This is critical for Core stability.
Per-Sender Overrides: Enabling users to select specific models for their sessions, a feature currently missing from Luna's Configuration.
Configurable Thresholds: Exposing compaction constants (like 50/20 messages) as configurable parameters rather than hardcoded values.

4.2 KiB Raw Blame History