How loves0ph1e/astrbot_plugin_readingsteiner works
1. What this repo is
- astrbot_plugin_readingsteiner is a Python plugin for AstrBot that adds long-term memory by delegating persistence and retrieval to an external EverOS memory service.
- The plugin itself does not store the full memory engine; it acts as an integration layer inside the AstrBot runtime.
2. Top-level boundary
- Inside this repo: AstrBot plugin logic, command handling, memory injection/archiving, identity resolution, filtering, and prompt synthesis.
- Outside this repo: the EverOS service, which is deployed separately and accessed over HTTP via core/everos_client.py.
- The deploy/ directory packages the EverOS side with Docker/Docker Compose; it is a sibling operational component, not embedded in the plugin process.
3. Main runtime flow
- The plugin works on two hooks around each conversation turn:
- Pre-request injection: fetch stable user profile + related memories and inject them into the model prompt.
- Post-response archiving: write the new turn back to EverOS so the user’s profile and episodic memory can evolve.
- This makes memory behavior symmetric: read before generation, write after generation.
4. Identity and isolation layer
- core/identity.py is the key boundary for user/session identification.
- The system treats the real sender identity as authoritative; memory is keyed by that identity, not by the model’s interpretation.
- The README’s “hard isolation” means this layer prevents cross-user memory mixing, especially in multi-user or group chat settings.
5. Memory injection subsystem
- core/injection.py and related modules assemble the context inserted into the LLM request.
- Injection combines:
- a persistent profile for the current user,
- top-k relevant scene memories from recent/history search,
- optional filtering based on group-chat privacy rules.
- core/visibility.py and config flags like group_public_only decide what is safe to expose in group contexts.
6. Memory synthesis and representation
- core/synthesis.py turns raw memory data into the readable Chinese structure described in the README: overall impression, explicit facts, implicit traits.
- core/relationship.py, core/profile_quality.py, and core/constants.py suggest the repo models memory not just as blobs, but as structured user-state plus relationship/quality metadata.
- This is important architecturally: the plugin is not a plain vector-recall wrapper; it is a profile-centric memory layer.
7. Archiving subsystem
- core/archiving.py handles writing conversation turns back to EverOS.
- The archive strategy is configurable (auto, every_turn, manual), so the write path can be event-driven or explicitly triggered.
- This write path is what lets EverOS incrementally update the user profile and memory graph over time.
8. Forget / suppression path
- core/forget.py implements “forgetting” as read-path suppression, not physical deletion.
- That distinction is architectural: the plugin can stop injecting or recalling specific memories, but the underlying EverOS data remains unless removed on the EverOS side.
- The repo therefore supports reversible opt-out behavior without needing disk-level access to the memory service.
9. Command and tool surfaces
- commands/handlers.py exposes user/admin commands like flush, status, search, quality, and forget.
- The README also mentions optional LLM tools (epk_recall, epk_remember), which means the plugin has both human control commands and model-invoked memory tools.
- These are separate access paths into the same memory subsystem, but both still depend on identity from the real message event.
10. Operational resilience
- The architecture is explicitly fail-soft: if EverOS is unreachable, the plugin logs the issue and lets normal chat continue.
- That means memory is an enhancement, not a hard dependency for core dialogue.
- The eventual-consistency note in the README also matters: archive and later search may not be immediately in sync.
11. Configuration and packaging
- _conf_schema.json is the plugin’s configuration contract for AstrBot’s UI/config system.
- main.py is the integration entrypoint, while metadata.yaml and pyproject.toml define plugin/package metadata.
- The deploy/ folder contains the operational packaging for EverOS, including environment defaults and container orchestration.
12. Test coverage implies the subsystem map
- The tests mirror the architecture: identity, injection, archiving, forgetting, visibility, synthesis, profile quality, EverOS client, and command handling.
- That strongly suggests the repo is organized around distinct functional boundaries rather than one monolithic plugin file.
13. Diagramming hint
- A correct architecture diagram should show:
- AstrBot message/event stream entering the plugin,
- identity extraction as the first gate,
- pre-generation injection from EverOS into the prompt,
- post-generation archiving back to EverOS,
- command/tool side channels into the same memory engine,
- and a separate deployment boundary for the EverOS service.
Main entry points: injection.py Injection · main.py Entry · everos_client.py EverOS Client · identity.py Identity
Components 18
Plugin Runtime
AstrBot plugin components that identify users, inject memory, and archive turns.
- Entry · Initializes the plugin integration and wires the runtime hooks.
main.py - Identity · Resolves the real sender identity and anchors memory isolation.
core/identity.py - Injection · Builds pre-generation memory context for the model prompt.
core/injection.py - Archiver · Sends conversation turns back for long-term memory updates.
core/archiving.py - Forget · Suppresses selected memories from recall without deleting upstream data.
core/forget.py - Visibility · Determines what memory is safe to expose, especially in groups.
core/visibility.py - Synthesis · Turns raw memory into readable profile and impression text.
core/synthesis.py - Quality · Scores or annotates profile confidence and state quality.
core/profile_quality.py - Relationship · Tracks relationship-oriented structure around the user profile.
core/relationship.py - Constants · Holds shared labels, limits, and memory structure constants.
core/constants.py - EverOS Client · Talks to the external EverOS memory service over HTTP.
core/everos_client.py - Config · AstrBot configuration contract for runtime behavior and privacy flags.
_conf_schema.json - Metadata · Plugin package metadata and distribution settings.
metadata.yaml
Controls
Human and tool-facing command surfaces for inspecting or changing memory behavior.
- Commands · Exposes flush, status, search, quality, and forget commands.
commands/handlers.py - Tools · Model-invoked recall and remember actions that reach the same memory engine.
Deployment
Operational packaging for the external EverOS service.
- Deploy · Docker-based packaging for the separately deployed EverOS service.
deploy/docker-compose.yml - EverOS · Separate persistence and retrieval backend used by the plugin.
Other components
- AstrBot · External chat runtime that loads the plugin and emits message events.
Connections 25
- AstrBot → Entry: loads · AstrBot loads the plugin entrypoint and starts hook wiring.
- Entry → Identity: gate · Every turn is keyed by the authoritative sender identity.
- Entry → Injection: pre-turn · Pre-generation hook assembles memory context before the model is called.
- Entry → Archiver: post-turn · Post-generation hook archives the completed exchange.
- Entry → Commands: admin path · Registers command handlers for memory inspection and control.
- Entry → Tools: tool path · Optional model tools access the same memory subsystem.
- Identity → Injection: scope · Identity resolution scopes which memories may be retrieved.
- Identity → Archiver: owner · Archiving writes back under the real sender identity.
- Identity → Forget: scope · Forget operations are also anchored to the resolved identity.
- Injection → Visibility: filter · Filters what can be exposed in the current conversation context.
- Injection → Synthesis: format · Builds readable profile text from structured memory data.
- Injection → Quality: annotate · Includes quality or confidence signals when composing context.
- Injection → Relationship: enrich · Pulls relationship-aware state into the injected memory view.
- Injection → Constants: rules · Uses shared limits and schema constants while assembling context.
- Injection → EverOS Client: retrieve · Fetches profile and relevant memories from EverOS.
- Archiver → EverOS Client: write · Sends new conversation turns to EverOS for persistence.
- Forget → EverOS Client: suppress · Applies read-path suppression against retrieved memories.
- Commands → Identity: auth · Command behavior follows the same sender identity boundary.
- Commands → EverOS Client: query · Status, search, and quality commands inspect the remote memory store.
- Commands → Forget: forget · User/admin commands can mark memories hidden from recall.
- Tools → EverOS Client: recall/remember · LLM tools invoke the same memory backend through the client.
- Config → Entry: configure · Configuration flags shape runtime behavior and privacy policy.
- Metadata → Entry: package · Package metadata defines how the plugin is distributed and loaded.
- Deploy → EverOS: runs · Deployment assets package the external EverOS service stack.
- EverOS Client → EverOS: http · The plugin communicates with EverOS over HTTP.