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

Short Memory: Recent action steps and observations (last ~50 items)
Episodic Memory: LLM-generated summaries of completed actions
Long Memory: Persistent markdown files (USER.md, LEARNING.md, JOURNAL.md)
Vector Memory: Semantic search index for embedding-based recall
Daily Memory: Append-only logs organized by date
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

query

string

required

Natural language description of what to recall. The system finds semantically similar memories, not just keyword matches.

limit

number

default:"10"

Maximum number of results to return

Return Value

results

string

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:

{
  "skill": "recall_memory",
  "args": {
    "query": "last deployment discussion",
    "limit": 5
  }
}

Find information about a user:

{
  "skill": "recall_memory",
  "args": {
    "query": "Alice's preferred communication style"
  }
}

Recall technical details:

{
  "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

info_text

string

required

Information to add to USER.md. Should be factual, concise, and actionable.

Return Value

result

string

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

{
  "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:

# 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

string

required

Topic to research and learn about

knowledge_content

string

Optional pre-researched content to save. If omitted, the skill automatically researches the topic.

Return Value

result

string

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:

{
  "skill": "update_learning",
  "args": {
    "topic": "WebAssembly 2025 capabilities"
  }
}

Save researched content:

{
  "skill": "update_learning",
  "args": {
    "topic": "Rust async traits",
    "knowledge_content": "Rust 1.75 stabilized async fn in traits. Enables dynamic dispatch with Box<dyn AsyncTrait>. 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

# 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

entry_text

string

required

Journal entry content. Should be introspective and reflective.

Return Value

result

string

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

{
  "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

# 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

string

required

Topic or question to analyze deeply

Return Value

analysis

string

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

{
  "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

string

required

Content to ingest (text, markdown, JSON, CSV, code)

source

string

required

Source identifier (e.g., “report.md”, “api-docs”)

collection

string

default:"default"

Collection name for organization

title

string

Document title

tags

array

Tags for filtering

format

string

Content format: text, markdown, csv, json, jsonl, code

Example:

{
  "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:

file_path

string

required

Path to the file to ingest

collection

string

Collection name

tags

array

rag_ingest_url

Download and ingest from a URL. Parameters:

url

string

required

URL to download and ingest

collection

string

Collection name

tags

array

rag_search

Semantic search across ingested documents. Parameters:

query

string

required

Search query

limit

number

default:"10"

Max results

collection

string

Search within specific collection

tags

array

Filter by tags

Example:

{
  "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:

collection

string

List specific collection (omit for all)

Example:

{
  "skill": "rag_list",
  "args": {}
}

rag_delete

Delete documents or entire collections. Parameters:

document_id

string

Specific document ID to delete

collection

string

Delete entire collection

Example:

{
  "skill": "rag_delete",
  "args": {
    "collection": "old-docs"
  }
}

Best Practices

Memory organization strategy:

Use recall_memory for recent conversations and context
Use update_user_profile for permanent user facts
Use update_learning for technical knowledge
Use update_journal for self-reflection
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.

Channels

Send context-aware messages

Scheduling

Schedule autonomous memory review

CLI Commands

Core Skills

Configuration

​Memory & Learning

​Memory Architecture

​Memory Types

​Memory Limits

​recall_memory

​Parameters

​Return Value

​Features

​Example Usage

​Response Example

​Metadata

​update_user_profile

​Parameters

​Return Value

​What to Store

​Example Usage

​USER.md Format

​Metadata

​update_learning

​Parameters

​Return Value

​Features

​Example Usage

​Response Example

​LEARNING.md Format

​Metadata

​update_journal

​Parameters

​Return Value

​What to Journal

​Example Usage

​JOURNAL.md Format

​Metadata

​deep_reason

​Parameters

​Return Value

​Use Cases

​Example Usage

​Response Example

​Metadata

​RAG Knowledge Store

​rag_ingest

​rag_ingest_file

​rag_ingest_url

​rag_search

​rag_list

​rag_delete

​Best Practices

​Related Skills

Channels

Scheduling

Memory & Learning

Memory Architecture

Memory Types

Memory Limits

recall_memory

Parameters

Return Value

Features

Example Usage

Response Example

Metadata

update_user_profile

Parameters

Return Value

What to Store

Example Usage

USER.md Format

Metadata

update_learning

Parameters

Return Value

Features

Example Usage

Response Example

LEARNING.md Format

Metadata

update_journal

Parameters

Return Value

What to Journal

Example Usage

JOURNAL.md Format

Metadata

deep_reason

Parameters

Return Value

Use Cases

Example Usage

Response Example

Metadata

RAG Knowledge Store

rag_ingest

rag_ingest_file

rag_ingest_url

rag_search

rag_list

rag_delete

Best Practices

Related Skills