Memory

Memory in Maestro provides conversation persistence across sessions and restarts.

How Memory Works

Each conversation is identified by a session ID:

• Telegram: Uses the chat ID
• CLI: Uses a fixed ID per terminal session
• REST API: Provided by the caller

When you send a message:

1. Maestro loads previous messages for your session
2. Your new message is appended
3. The full history is sent to the LLM
4. The response is stored in memory

What’s Stored

Each message includes:

Field	Description
role	user, assistant, or tool
content	Message text
timestamp	When the message was sent
toolCalls	Tool calls made (if any)
toolResults	Results from tool execution

Storage Backend

Maestro uses SQLite for memory:

• File location: data/maestro.db
• Auto-created: Database is created on first run
• Persistent: Survives restarts
• Self-contained: No external database needed

Note

SQLite is sufficient for most use cases. For high-volume production deployments, you could extend the memory provider to use PostgreSQL or Redis.

Session Management

Viewing History

REST API:

curl http://localhost:3000/chat/session-123

CLI:

/history

Clearing History

CLI:

/clear

This clears the current session’s history but doesn’t affect other sessions.

Memory and Agents

Memory is session-scoped, not agent-scoped:

• All agents in a conversation share the same memory
• If the orchestrator routes to different agents, they all see the history
• This enables context continuity across agent switches

You: What's the capital of France?
[personal-assistant responds: Paris]

You: Write a Python function to fetch weather for that city
[coder agent sees the previous exchange and knows "that city" = Paris]

Dynamic Agents and Memory

Dynamic agents (created through conversation) are also stored in SQLite:

• Agent configurations persist across restarts
• Separate from session memory
• Can be updated, listed, and deleted via tools

Memory Limits

Long conversations can exceed the LLM’s context window. Maestro handles this by:

1. Including recent messages up to the context limit
2. Older messages may be truncated from the LLM’s view
3. All messages remain stored in SQLite

Tip

If a conversation gets very long, start a new session with /clear or create a fresh session ID.

Data Location

data/
└── maestro.db       # SQLite database
    ├── sessions     # Conversation history
    └── agents       # Dynamic agent configs

The data/ directory is gitignored by default.

Backup and Recovery

To backup your data:

cp data/maestro.db data/maestro.db.backup

To restore:

cp data/maestro.db.backup data/maestro.db

For production, consider automated backups.