# lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory architecture

> Architecture diagram of the GitHub repository lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory
- Repository: https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory

## Overview

LivingMemory is an AstrBot plugin for capturing, organizing, retrieving, and maintaining long-term conversational memories. Its main workflow begins with conversation events, processes them into memories, and later recalls relevant memories through hybrid document and graph search for context-aware use. Users can also manage memories, profiles, prompts, diagnostics, and graph views in the dashboard or invoke agentic memory tools. The README documents these capabilities; several subsystem links below are documented rather than confirmed from sampled implementation, and are marked accordingly.

Main entry points: [`core/managers/memory_engine.py`](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine.py) (Memory engine), [`pages/dashboard/app.js`](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/pages/dashboard/app.js) (Dashboard), [`core/event_handler.py`](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/event_handler.py) (Conversation events), [`core/command_handler.py`](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/command_handler.py) (Plugin commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Plugin runtime"]
  node_conversation["Conversation events<br/>[event_handler.py]"]
  node_commands["Plugin commands<br/>[command_handler.py]"]
  node_config["Configuration<br/>[config_manager.py]"]
end

subgraph group_memory["Memory lifecycle"]
  node_processor["Memory processing"]
  node_engine["Memory engine<br/>[memory_engine.py]"]
  node_crud["Memory CRUD"]
  node_lifecycle["Lifecycle management"]
  node_conversation_store["Conversation history"]
  node_profiles["Profiles<br/>[profile_manager.py]"]
  node_atom_store[("Memory atom store<br/>[atom_store.py]")]
  node_graph_store[("Memory graph<br/>[graph_store.py]")]
end

subgraph group_recall["Recall and agents"]
  node_hybrid["Hybrid retrieval"]
  node_vector["Vector retrieval"]
  node_recall_engine["Recall engine"]
  node_agentic["Agentic recall"]
  node_tools["Memory tools"]
  node_trace["Recall traces<br/>[recall_trace.py]"]
end

subgraph group_management["Management interface"]
  node_page_api["Dashboard API<br/>[page_api.py]"]
  node_dashboard["Dashboard<br/>[app.js]"]
  node_external_api["External API<br/>[external_api.py]"]
  node_prompts["Prompt management<br/>[prompt_manager.py]"]
end

node_astrbot(("AstrBot"))
node_embedding{{"Embedding provider"}}

node_astrbot -->|"delivers events"| node_conversation
node_astrbot -.->|"invokes commands"| node_commands
node_conversation -->|"dispatches processing"| node_processor
node_conversation -->|"uses memory engine"| node_engine
node_commands -->|"manages memories"| node_engine
node_commands -->|"uses history manager"| node_conversation_store
node_config -.->|"configures memory"| node_engine
node_processor -.->|"creates memories"| node_engine
node_engine -->|"delegates writes"| node_crud
node_engine -->|"delegates recall"| node_recall_engine
node_engine -->|"delegates maintenance"| node_lifecycle
node_engine -->|"uses atom storage"| node_atom_store
node_engine -->|"uses graph storage"| node_graph_store
node_crud -->|"writes atoms"| node_atom_store
node_crud -.->|"indexes graph"| node_graph_store
node_recall_engine -->|"searches memories"| node_hybrid
node_hybrid -->|"runs vector route"| node_vector
node_embedding -.->|"provides embeddings"| node_vector
node_recall_engine -.->|"records recall"| node_trace
node_tools -->|"requests recall"| node_agentic
node_agentic -->|"retrieves candidates"| node_hybrid
node_page_api -->|"delegates external requests"| node_external_api
node_dashboard -.->|"calls dashboard API"| node_page_api
node_dashboard -.->|"manages prompts"| node_prompts
node_dashboard -.->|"manages profiles"| node_profiles

click node_conversation "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/event_handler.py"
click node_commands "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/command_handler.py"
click node_config "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/base/config_manager.py"
click node_processor "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/processors/memory_processor.py"
click node_engine "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine.py"
click node_crud "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_crud.py"
click node_lifecycle "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_batch.py"
click node_conversation_store "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/conversation_manager.py"
click node_profiles "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/profile_manager.py"
click node_atom_store "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/storage/atom_store.py"
click node_graph_store "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/storage/graph_store.py"
click node_hybrid "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/hybrid_retriever.py"
click node_vector "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/vector_retriever.py"
click node_recall_engine "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_recall.py"
click node_agentic "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_agentic.py"
click node_tools "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/tools/memory_agentic_search_tool.py"
click node_trace "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/recall_trace.py"
click node_page_api "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/page_api.py"
click node_dashboard "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/pages/dashboard/app.js"
click node_external_api "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/external_api.py"
click node_prompts "https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/prompts/prompt_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_conversation,node_commands,node_config toneBlue
class node_processor,node_engine,node_crud,node_lifecycle,node_conversation_store,node_profiles,node_atom_store,node_graph_store toneAmber
class node_hybrid,node_vector,node_recall_engine,node_agentic,node_tools,node_trace toneMint
class node_page_api,node_dashboard,node_external_api,node_prompts toneRose
class node_astrbot,node_embedding toneIndigo
```

## Components

### Plugin runtime

- [Conversation events](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/event_handler.py): `core/event_handler.py`
- [Plugin commands](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/command_handler.py): `core/command_handler.py`
- [Configuration](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/base/config_manager.py): `core/base/config_manager.py`

### Memory lifecycle

- [Memory processing](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/processors/memory_processor.py): `core/processors/memory_processor.py`
- [Memory engine](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine.py): `core/managers/memory_engine.py`
- [Memory CRUD](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_crud.py): `core/managers/memory_engine_crud.py`
- [Lifecycle management](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_batch.py): `core/managers/memory_engine_batch.py`
- [Conversation history](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/conversation_manager.py): `core/managers/conversation_manager.py`
- [Profiles](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/profile_manager.py): `core/managers/profile_manager.py`
- [Memory atom store](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/storage/atom_store.py): `storage/atom_store.py`
- [Memory graph](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/storage/graph_store.py): `storage/graph_store.py`

### Recall and agents

- [Hybrid retrieval](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/hybrid_retriever.py): `core/retrieval/hybrid_retriever.py`
- [Vector retrieval](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/vector_retriever.py): `core/retrieval/vector_retriever.py`
- [Recall engine](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_recall.py): `core/managers/memory_engine_recall.py`
- [Agentic recall](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/managers/memory_engine_agentic.py): `core/managers/memory_engine_agentic.py`
- [Memory tools](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/tools/memory_agentic_search_tool.py): `core/tools/memory_agentic_search_tool.py`
- [Recall traces](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/retrieval/recall_trace.py): `core/retrieval/recall_trace.py`

### Management interface

- [Dashboard API](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/page_api.py): `core/page_api.py`
- [Dashboard](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/pages/dashboard/app.js): `pages/dashboard/app.js`
- [External API](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/external_api.py): `core/external_api.py`
- [Prompt management](https://github.com/lxfight-s-astrbot-plugins/astrbot_plugin_livingmemory/blob/master/core/prompts/prompt_manager.py): `core/prompts/prompt_manager.py`

### Other components

- **AstrBot**
- **Embedding provider**

## Connections

- AstrBot → Conversation events: delivers events (evidence: `core/event_handler.py`)
- AstrBot → Plugin commands: invokes commands
- Conversation events → Memory processing: dispatches processing (evidence: `core/event_handler.py`)
- Conversation events → Memory engine: uses memory engine (evidence: `core/event_handler.py`)
- Plugin commands → Memory engine: manages memories (evidence: `core/command_handler.py`)
- Plugin commands → Conversation history: uses history manager (evidence: `core/command_handler.py`)
- Configuration → Memory engine: configures memory
- Memory processing → Memory engine: creates memories
- Memory engine → Memory CRUD: delegates writes (evidence: `core/managers/memory_engine.py`)
- Memory engine → Recall engine: delegates recall (evidence: `core/managers/memory_engine.py`)
- Memory engine → Lifecycle management: delegates maintenance (evidence: `core/managers/memory_engine.py`)
- Memory engine → Memory atom store: uses atom storage (evidence: `core/managers/memory_engine.py`)
- Memory engine → Memory graph: uses graph storage (evidence: `core/managers/memory_engine.py`)
- Memory CRUD → Memory atom store: writes atoms (evidence: `core/managers/memory_engine_crud.py`)
- Memory CRUD → Memory graph: indexes graph
- Recall engine → Hybrid retrieval: searches memories (evidence: `core/managers/memory_engine_recall.py`)
- Hybrid retrieval → Vector retrieval: runs vector route (evidence: `core/retrieval/hybrid_retriever.py`)
- Embedding provider → Vector retrieval: provides embeddings (evidence: `README.md`)
- Recall engine → Recall traces: records recall (evidence: `core/managers/memory_engine_recall.py`)
- Memory tools → Agentic recall: requests recall (evidence: `core/tools/memory_agentic_search_tool.py`)
- Agentic recall → Hybrid retrieval: retrieves candidates (evidence: `core/managers/memory_engine_agentic.py`)
- Dashboard API → External API: delegates external requests
- Dashboard → Dashboard API: calls dashboard API
- Dashboard → Prompt management: manages prompts
- Dashboard → Profiles: manages profiles