Message Store

Message Store

Lingchu Bot includes an optional message storage service that records event data, processing results, bot lifecycle events, and platform API call summaries. This page explains what is stored, how to configure it, and how to access stored data.

Overview

The message store is split into three layers:

Layer	File	Responsibility
Platform adapter	hooks/adapters.py	Resolves Bot/Event to a stable platform context and normalizes events into adapter-neutral metadata.
Hook registration	hooks/handlers/message_store.py	Registers NoneBot event_preprocessor, event_postprocessor, run_preprocessor, and run_postprocessor hooks.
Business logic	services/message_store.py	Writes event receipts, processing results, lifecycle records, and API call summaries through the repository layer.

The service records structured summaries rather than raw message content. Events are routed through repository-level model selection so high-volume platform/adapter/framework combinations can use dedicated ORM tables.

Optional feature

Message storage is enabled by default but can be disabled entirely by setting LINGCHU_MESSAGE_STORE_ENABLED=false in the NoneBot environment or its .env files. Deployment fields are not read from config.toml; only online-editable overrides, such as command triggers, are stored in runtime-overrides.toml.

What is stored

Record type	Description
Event receipt	When any adapter event is received by the bot
Processing result	The outcome of handling an event
Bot lifecycle	Startup, shutdown, and connection events
API call summary	Platform API calls made during event handling

Each record includes platform, adapter, framework, event category, and adapter event type fields. QQ + OneBot V11 + NoneBot events are stored in dedicated partition tables; unsupported combinations fall back to the legacy global tables.

Configuration

Field	Type	Default	Description
message_store_enabled	boolean	true	Whether to enable message-store runtime hooks
message_store_retention_days	number	30	Number of days to retain message records; 0 disables day-based expiry
message_store_summary_limit	number	500	Maximum length for text, data, and result summaries
message_store_record_api_calls	boolean	true	Whether to record platform API call summaries
message_store_cleanup_enabled	boolean	true	Whether to clean expired message records during shutdown

Data retention

Records are retained based on message_store_retention_days:

• When set to a positive number, records older than the specified days are cleaned up.
• When set to 0, day-based expiry is disabled; records are kept indefinitely.
• Cleanup runs during bot shutdown when message_store_cleanup_enabled is true.

Platform identification

The platform field in stored records is derived from the adapter registry:

Scenario	Platform value
OneBot V11 adapter enabled	qq
Unknown adapter	unknown

Only the adapter selected by LINGCHUAdapter determines the platform value. Other registered adapters are ignored.

Storage backend

Message store uses nonebot-plugin-orm for database access. The ORM helper in database/orm_crud.py provides async CRUD operations that run in worker threads to avoid blocking the NoneBot event loop.

Blocking paths

File storage, TOML parsing, deepcopy, command parsing, and translation catalog loading are all moved to worker threads. Do not call synchronous storage methods directly from async handlers.

Disabling message store

To disable message storage entirely:

message_store_enabled = false

When disabled, no event hooks are registered and no records are written. Existing records are not automatically deleted.