> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt > Use this file to discover all available pages before exploring further. # Memory & Learning > Semantic memory, user profiles, RAG knowledge store, and autonomous learning # Memory & Learning OrcBot's memory system provides multi-layered storage for conversations, user preferences, learned knowledge, and semantic search capabilities. The memory architecture supports both short-term operational memory and long-term persistent storage. ## Memory Architecture ### Memory Types 1. **Short Memory**: Recent action steps and observations (last \~50 items) 2. **Episodic Memory**: LLM-generated summaries of completed actions 3. **Long Memory**: Persistent markdown files (USER.md, LEARNING.md, JOURNAL.md) 4. **Vector Memory**: Semantic search index for embedding-based recall 5. **Daily Memory**: Append-only logs organized by date 6. **Contact Profiles**: Per-contact relationship context (WhatsApp) ### Memory Limits * **Context limit**: 50 short memories (configurable via `memoryContextLimit`) * **Episodic limit**: 200 summaries (configurable via `memoryEpisodicLimit`) * **Consolidation threshold**: 30 short memories before summarization * **Memory content max**: 500 characters per entry * **Flush interval**: Auto-flush when soft threshold reached ## recall\_memory Semantic search across ALL memory types. This is the primary skill for recalling past conversations and context. ### Parameters Natural language description of what to recall. The system finds semantically similar memories, not just keyword matches. Maximum number of results to return ### Return Value Formatted list of relevant memories with timestamps, types, sources, and relevance scores. ### Features * **Semantic search**: Uses vector embeddings for meaning-based recall (when configured) * **Cross-channel**: Searches across Telegram, WhatsApp, Discord, Slack, email * **Multi-type**: Searches short, episodic, and long-term memory * **Keyword fallback**: Falls back to keyword search if vector memory unavailable * **Ranked results**: Sorted by relevance score (semantic) or recency (keyword) ### Example Usage **Recall recent deployment discussion:** ```json theme={null} { "skill": "recall_memory", "args": { "query": "last deployment discussion", "limit": 5 } } ``` **Find information about a user:** ```json theme={null} { "skill": "recall_memory", "args": { "query": "Alice's preferred communication style" } } ``` **Recall technical details:** ```json theme={null} { "skill": "recall_memory", "args": { "query": "API endpoint for user authentication" } } ``` ### Response Example ``` Found 5 relevant memories: 1. [2025-01-15T14:30:00Z] (short [telegram], relevance: 95%) User mentioned the deployment is scheduled for Friday at 6 PM EST. Must coordinate with DevOps team. 2. [2025-01-15T10:15:00Z] (episodic [telegram], relevance: 87%) Completed action: Research deployment checklist. Found 12-step process including database backup, staging verification, and rollback plan. 3. [2025-01-14T16:45:00Z] (short [whatsapp], relevance: 78%) Frederick asked about deployment timeline for the new feature. Needs to be live before Monday. [2 more results] ``` ### Metadata * **isDeep**: `false` - Memory operations are fast * **isParallelSafe**: `true` **Use natural language queries.** The semantic search understands meaning, so "when is the deployment?" works better than "deployment date". ## update\_user\_profile Permanently persist information learned about the user. ### Parameters Information to add to USER.md. Should be factual, concise, and actionable. ### Return Value Confirmation that the profile was updated ### What to Store **Store:** * User preferences ("prefers concise answers", "works in PST timezone") * Core identity (name, role, company, location) * Communication style ("direct and technical") * Important relationships ("team lead for Project X") * Constraints and requirements ("Python 3.11 only", "no external dependencies") **Don't store:** * Ephemeral information ("currently working on feature Y") * Passwords or secrets * Detailed conversation logs (use memory for that) * Information that changes frequently ### Example Usage ```json theme={null} { "skill": "update_user_profile", "args": { "info_text": "User prefers Python for data analysis tasks. Familiar with pandas, numpy, and scikit-learn." } } ``` ### USER.md Format The skill appends to `USER.md` in a structured format: ```markdown theme={null} # User Profile ## Core Identity - Name: Frederick - Role: Engineering Lead - Timezone: PST (UTC-8) ## Preferences - Prefers concise, technical communication - Python for data analysis - Familiar with pandas, numpy, scikit-learn ## Constraints - No external API dependencies for production code - Must support Python 3.11+ ``` ### Metadata * **isDeep**: `false` * **isDangerous**: `false` **USER.md is long-term memory.** Only store information that's likely to remain relevant for weeks or months. Don't spam it with ephemeral details. ## update\_learning Research a topic and persist knowledge to LEARNING.md. ### Parameters Topic to research and learn about Optional pre-researched content to save. If omitted, the skill automatically researches the topic. ### Return Value Confirmation with a summary of what was learned ### Features * **Auto-research**: If no content provided, uses `web_search` or LLM to gather info * **Structured storage**: Organizes knowledge by topic headings * **LLM extraction**: Uses fast model to distill key facts (capped at 3000 chars input) * **Size limits**: Per-entry cap of 3000 chars to prevent bloat ### Example Usage **Auto-research:** ```json theme={null} { "skill": "update_learning", "args": { "topic": "WebAssembly 2025 capabilities" } } ``` **Save researched content:** ```json theme={null} { "skill": "update_learning", "args": { "topic": "Rust async traits", "knowledge_content": "Rust 1.75 stabilized async fn in traits. Enables dynamic dispatch with Box. No more async-trait crate needed for most use cases. Limitations: no GATs in async traits yet." } } ``` ### Response Example ``` Learning updated: WebAssembly 2025 capabilities Key facts: - WASM Component Model now stable - Native multi-threading support via shared memory - WASI Preview 2 enables filesystem and network I/O - Performance within 5% of native C++ for compute-heavy tasks ``` ### LEARNING.md Format ```markdown theme={null} # Agent Learning Base This file contains structured knowledge on various topics. ## WebAssembly 2025 Capabilities The WebAssembly Component Model is now stable, enabling modular composition... ## Rust Async Traits Rust 1.75 stabilized async fn in traits... ``` ### Metadata * **isDeep**: `true` - Research operations are substantive * **isResearch**: `false` **LEARNING.md is for technical knowledge.** Use it to build a knowledge base of programming concepts, frameworks, APIs, and technical patterns you encounter. ## update\_journal Write a self-reflection entry to JOURNAL.md. ### Parameters Journal entry content. Should be introspective and reflective. ### Return Value Confirmation that the journal was updated ### What to Journal * Reflections on complex tasks * Lessons learned from failures * Insights about user behavior or preferences * Self-improvement observations * Strategic thinking about long-term goals ### Example Usage ```json theme={null} { "skill": "update_journal", "args": { "entry_text": "Today I helped the user debug a complex async race condition. I learned that asking clarifying questions about the execution environment (Node.js version, runtime) is more valuable than guessing solutions. Next time, I'll start with system_check." } } ``` ### JOURNAL.md Format ```markdown theme={null} # Agent Journal ## 2025-01-15 Today I helped the user debug a complex async race condition... ## 2025-01-14 Reflection: I've noticed that users appreciate concise status updates... ``` ### Metadata * **isDeep**: `false` ## deep\_reason Perform intensive multi-step chain-of-thought analysis. ### Parameters Topic or question to analyze deeply ### Return Value Multi-step reasoning output with conclusions and insights ### Use Cases * Ethical dilemmas ("Should we prioritize speed or security?") * Complex technical decisions ("Which database architecture?") * Strategic planning ("How to scale this system to 1M users?") * Root cause analysis ("Why did this deployment fail?") ### Example Usage ```json theme={null} { "skill": "deep_reason", "args": { "topic": "Trade-offs between microservices and monolith for our team size" } } ``` ### Response Example ``` Deep Reasoning: Microservices vs Monolith Trade-offs Step 1: Context Analysis - Team size: 5 engineers - Current system: monolithic Rails app - Pain point: slow CI/CD, everything deploys together Step 2: Microservices Benefits + Independent deployment + Technology diversity + Clearer service boundaries Step 3: Microservices Costs - Operational complexity (orchestration, monitoring, tracing) - Network latency and failure modes - Requires DevOps expertise Step 4: Monolith Benefits + Simple deployment model + Easy local development + Strong consistency guarantees Step 5: Recommendation For a 5-person team, a well-structured modular monolith is likely optimal. Consider: 1. Separate deployment artifacts per module (still within one repo) 2. Clear module boundaries with enforced interfaces 3. Defer microservices until team >15 or clear scaling bottleneck Conclusion: Start with modular monolith, plan migration path. ``` ### Metadata * **isDeep**: `true` * **isResearch**: `false` ## RAG Knowledge Store The RAG (Retrieval-Augmented Generation) knowledge store provides persistent, searchable document storage with semantic search. ### rag\_ingest Ingest content into the knowledge store. **Parameters:** Content to ingest (text, markdown, JSON, CSV, code) Source identifier (e.g., "report.md", "api-docs") Collection name for organization Document title Tags for filtering Content format: text, markdown, csv, json, jsonl, code **Example:** ```json theme={null} { "skill": "rag_ingest", "args": { "content": "# API Documentation\n\n## Authentication\nUse Bearer tokens...", "source": "api-docs.md", "collection": "documentation", "title": "API Documentation", "tags": ["api", "auth", "docs"], "format": "markdown" } } ``` ### rag\_ingest\_file Ingest a local file. **Parameters:** Path to the file to ingest Collection name Tags Document title **Example:** ```json theme={null} { "skill": "rag_ingest_file", "args": { "file_path": "/home/user/.orcbot/workspace/README.md", "collection": "project-docs" } } ``` ### rag\_ingest\_url Download and ingest from a URL. **Parameters:** URL to download and ingest Collection name Tags Document title **Features:** * Auto-detects HTML and applies Readability extraction * Handles plain text, markdown, JSON * Preserves metadata (URL, fetch date) **Example:** ```json theme={null} { "skill": "rag_ingest_url", "args": { "url": "https://docs.example.com/api", "collection": "external-docs", "tags": ["api", "reference"] } } ``` ### rag\_search Semantic search across ingested documents. **Parameters:** Search query Max results Search within specific collection Filter by tags **Example:** ```json theme={null} { "skill": "rag_search", "args": { "query": "how to authenticate API requests", "collection": "documentation", "limit": 5 } } ``` **Response Example:** ``` Found 5 relevant chunks: 1. [api-docs.md] (score: 0.92) ## Authentication Use Bearer tokens in the Authorization header. Tokens expire after 24 hours... 2. [security-guide.md] (score: 0.85) API requests must include a valid JWT token. Obtain tokens via POST /auth/login... [3 more results] ``` ### rag\_list List documents and collections. **Parameters:** List specific collection (omit for all) **Example:** ```json theme={null} { "skill": "rag_list", "args": {} } ``` ### rag\_delete Delete documents or entire collections. **Parameters:** Specific document ID to delete Delete entire collection **Example:** ```json theme={null} { "skill": "rag_delete", "args": { "collection": "old-docs" } } ``` ## Best Practices **Memory organization strategy:** 1. Use `recall_memory` for recent conversations and context 2. Use `update_user_profile` for permanent user facts 3. Use `update_learning` for technical knowledge 4. Use `update_journal` for self-reflection 5. Use RAG for large documents and external knowledge **Avoid memory bloat:** * Keep USER.md entries concise (under 100 words each) * Don't duplicate information across memory types * Use RAG for large documents instead of update\_learning * Let consolidation happen automatically **Vector memory requires API keys.** Semantic search needs `openaiApiKey` or `googleApiKey`. Without it, the system falls back to keyword search. ## Related Skills Send context-aware messages Schedule autonomous memory review