How rixz-dev/base-ryn-ai works
1. What this repo is
- A Node.js virtual assistant / chat-bot called RYN AI.
- The architecture is centered on conversation handling, memory/state, LLM calls, and background automation.
- It is not a full product yet; README explicitly says this is a base version.
2. Process entry and runtime
- index.js is the main application entrypoint.
- ecosystem.config.js suggests it is meant to run under a process manager such as PM2.
- .env holds runtime configuration for API keys, tokens, and environment-specific settings.
3. Inbound interaction layer
- handlers/message.js handles text/chat messages.
- handlers/photo.js handles image inputs.
- These handlers are the main boundary between external user input and the assistant’s internal orchestration.
4. AI client boundary
- ai/client.js is the core adapter to the model/provider layer.
- The README points to NVIDIA NIM as the intended AI backend.
- This module likely isolates prompt submission, response parsing, and provider-specific calls from the rest of the app.
5. Cognitive state / “brain” subsystem
- The brain/ folder is the assistant’s internal state and reasoning layer.
- brain/memory.js stores or retrieves conversational context and long-term recall.
- brain/mood.js and brain/emotion.js track inferred user/assistant state.
- brain/dates.js likely normalizes time-related context and date awareness.
- brain/prompt.js assembles the system/context prompt sent to the model.
- brain/consolidation.js suggests periodic summarization or memory compression.
6. Tooling and capability layer
- tools/ contains external-action modules the assistant can invoke.
- tools/search.js, tools/weather.js, tools/reader.js, and tools/digest.js are web/data utilities.
- tools/vision.js and tools/voice.js represent multimodal capabilities, though the README notes these are currently error-prone.
- tools/index.js likely exports or routes available tools to the AI orchestration layer.
7. Typical request flow
- User message/photo arrives through a handler.
- The handler consults the brain layer for memory, mood, date context, and prompt construction.
- The AI client sends the composed prompt to the model.
- If the model or orchestrator decides a tool is needed, a module in tools/ is called.
- The result is merged back into the conversation response and possibly stored in memory.
8. Background automation
- scheduler/cron.js indicates scheduled jobs.
- This is where autonomous features live: reminders, periodic notifications, consolidation, or digest generation.
- This subsystem is separate from live chat handling and runs on a time trigger rather than user input.
9. Autonomous behavior and notifications
- The README calls out “auto notification” and “autonomous,” which implies the bot can initiate actions without a direct message.
- That behavior most likely depends on the scheduler plus brain/memory state to decide when to notify or summarize.
10. External dependencies and integration points
- The main external boundary is the LLM provider via ai/client.js.
- The web-related tools likely depend on third-party services for search, weather, and content reading.
- Voice and vision are present as planned features, but the README suggests they are not stable yet.
11. State and persistence
- Memory is a first-class architectural concern here, not an afterthought.
- The brain/ modules imply the assistant maintains both short-term conversation context and longer-lived remembered facts.
- brain/consolidation.js likely transforms accumulated interactions into smaller stored summaries.
12. Diagramming summary
- The clearest architecture diagram should show four main zones:
- Inbound handlers (message, photo)
- Brain/orchestration (memory, prompt, emotion, mood, dates, consolidation)
- AI + tools (ai/client, tools/*)
- Schedulers/automation (scheduler/cron)
- The central control flow is: user input or scheduled event → brain context → AI client → optional tools → response/notification → memory update.
Main entry points: message.js Text handler · index.js Tool router · cron.js Cron · memory.js Memory
Components 19
Runtime
Process entry and deployment
- App entry · Main application bootstrap and runtime wiring
index.js - PM2 config · Process manager configuration for deployment/runtime
ecosystem.config.js
Inbound
User-facing input handlers
- Text handler · Routes incoming text messages into assistant flow
handlers/message.js - Photo handler · Handles image-based user input
handlers/photo.js
Brain
State, context, and prompt assembly
- Memory · Conversation context and longer-term recall
brain/memory.js - Prompt builder · Builds the system and conversation prompt
brain/prompt.js - Emotion · Tracks inferred emotional state
brain/emotion.js - Mood · Tracks assistant or user mood signals
brain/mood.js - Dates · Normalizes date and time-aware context
brain/dates.js - Consolidation · Compresses or summarizes accumulated memory
brain/consolidation.js
AI + Tools
Model client and callable capabilities
- AI client · Provider boundary for model calls and response handling
ai/client.js - Tool router · Exposes available assistant tools
tools/index.js - Search · Searches external sources
tools/search.js - Weather · Fetches weather data
tools/weather.js - Reader · Reads or extracts content from sources
tools/reader.js - Digest · Produces digests or summaries
tools/digest.js - Vision · Image-related capability, currently unstable
tools/vision.js - Voice · Audio-related capability, currently unstable
tools/voice.js
Automation
Scheduled background work
- Cron · Runs autonomous and periodic background jobs
scheduler/cron.js
Connections 27
- App entry → Text handler: wires · Bootstraps text message handling
- App entry → Photo handler: wires · Bootstraps photo handling
- App entry → Cron: starts · Starts background automation
- App entry → PM2 config: deploys with · Designed to run under process manager config
- Text handler → Memory: reads/writes · Uses conversation state and recall
- Text handler → Prompt builder: builds · Composes prompt context for the model
- Text handler → Emotion: consults · Incorporates emotional state
- Text handler → Mood: consults · Incorporates mood signals
- Text handler → Dates: consults · Adds time-aware context
- Text handler → AI client: calls · Sends the assembled prompt to the model layer
- Photo handler → Memory: reads/writes · Uses conversation state and recall
- Photo handler → Prompt builder: builds · Composes multimodal prompt context
- Photo handler → AI client: calls · Sends image-aware requests to the model layer
- Prompt builder → AI client: feeds · Provides the final context passed to the LLM
- Memory → Consolidation: supplies · Provides accumulated state for summarization
- Consolidation → Memory: updates · Writes compact summaries back into memory
- AI client → Tool router: enables tools · Allows model-driven tool invocation
- Tool router → Search: exports · Registers search capability
- Tool router → Weather: exports · Registers weather capability
- Tool router → Reader: exports · Registers reader capability
- Tool router → Digest: exports · Registers digest capability
- Tool router → Vision: exports · Registers vision capability
- Tool router → Voice: exports · Registers voice capability
- Cron → Consolidation: runs · Triggers periodic memory consolidation
- Cron → Digest: runs · Generates scheduled digests and updates
- Cron → Memory: consults · Uses stored state for autonomous actions
- Cron → AI client: calls · Can initiate model-backed background tasks