moxxy

Memory System ​

Moxxy agents have a sophisticated memory system that enables them to remember conversations, learn from interactions, and maintain context over time.

Overview ​

┌─────────────────────────────────────────────────────┐
│                    Memory System                     │
├─────────────────────────────────────────────────────┤
│                                                      │
│  ┌─────────────────┐    ┌─────────────────┐        │
│  │  Short-Term     │    │   Long-Term     │        │
│  │  Memory (STM)   │    │   Memory (LTM)  │        │
│  │                 │    │                 │        │
│  │  • Recent turns │    │  • Facts        │        │
│  │  • Session ctx  │    │  • Embeddings   │        │
│  │  • current.md   │    │  • Semantic     │        │
│  └─────────────────┘    └─────────────────┘        │
│                                                      │
│  ┌─────────────────┐    ┌─────────────────┐        │
│  │     Swarm       │    │   Scheduled     │        │
│  │     Memory      │    │      Jobs       │        │
│  │                 │    │                 │        │
│  │  • Shared facts │    │  • Cron tasks   │        │
│  │  • Agent comms  │    │  • Heartbeats   │        │
│  └─────────────────┘    └─────────────────┘        │
│                                                      │
└─────────────────────────────────────────────────────┘

Short-Term Memory (STM) ​

STM holds the current conversation context - recent messages and the active session.

Characteristics ​

  • Fast access - In-memory + SQLite cache
  • Session-scoped - Tied to current conversation
  • Limited window - Last N turns (configurable)
  • Human-readable - Exported to current.md

Storage ​

ComponentLocationPurpose
SQLite tablememory.dbPersistent store
current.mdAgent workspaceHuman-readable snapshot
In-memory cacheRuntimeFast access

Session Management ​

Each conversation has a unique session ID:

Session: sess_abc123
├── User: Hello
├── Agent: Hi! How can I help?
├── User: What's the weather?
└── Agent: Let me check...

Start New Session ​

In TUI:

/new

Via API:

bash
POST /api/agents/default/session/new

current.md ​

A human-readable snapshot of STM:

markdown
# Agent Short-Term Memory Context

## Session: sess_abc123
## Last Updated: 2024-01-15 10:30:00

### Recent Messages

**User:** What files are in my Downloads folder?

**Agent:** I found 15 files in your Downloads folder:
- report.pdf
- image.png
- ...

**User:** Can you open the PDF?

**Agent:** I'll open report.pdf for you.
<invoke name="host_shell">["open ~/Downloads/report.pdf"]</invoke>

Long-Term Memory (LTM) ​

LTM stores persistent knowledge that survives across sessions.

Characteristics ​

  • Durable - Persists indefinitely
  • Semantic search - Vector embeddings for similarity
  • Fact extraction - Important information saved
  • Cross-session - Available in future conversations

Vector Embeddings ​

LTM uses sqlite-vec for semantic search:

sql
-- Memory entries with embeddings
CREATE TABLE long_term_memory (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding BLOB,  -- Vector embedding
    created_at DATETIME
);

-- Semantic search
SELECT content 
FROM long_term_memory 
ORDER BY vector_distance(embedding, ?) 
LIMIT 5;

How It Works ​

  1. Agent responds - Generates response to user
  2. Important facts extracted - Key information identified
  3. Embeddings created - Facts converted to vectors
  4. Stored in LTM - Persisted with embeddings

Semantic Retrieval ​

When the agent needs context:

User: "What did we discuss about the API last week?"

System:
1. Embed query: "API discussion last week"
2. Search LTM for similar vectors
3. Return top-k relevant memories
4. Inject into context

Agent: Based on our previous discussion, we talked about...

Swarm Memory ​

Shared knowledge base across all agents.

Characteristics ​

  • Global - All agents can read/write
  • Announcements - Agents share discoveries
  • Collaborative - Learn from each other

How Agents Share ​

Agents announce facts using special tags:

xml
[ANNOUNCE] The production API is experiencing 503 errors

Other agents can then access this knowledge:

User (to Agent B): Is there anything I should know about?

Agent B (retrieves from swarm): The production API is currently
experiencing issues. You may want to check on that.

Storage ​

Swarm memory is stored in a shared database:

~/.moxxy/swarm.db

Use Cases ​

  • Shared alerts - System issues, important events
  • Knowledge sharing - Learned facts, discoveries
  • Coordination - Task status, progress updates

Scheduled Jobs ​

Memory system also stores scheduled tasks:

sql
CREATE TABLE scheduled_jobs (
    name TEXT PRIMARY KEY,
    cron TEXT NOT NULL,        -- Cron expression
    prompt TEXT NOT NULL,      -- What to execute
    source TEXT NOT NULL,      -- Who created it
    created_at DATETIME
);

Managing Schedules ​

Create:

Schedule a daily summary at 9am

List:

Show me all scheduled jobs

Remove:

Cancel the daily summary job

Memory API ​

Endpoints ​

MethodEndpointDescription
GET/api/agents/:name/memory/stmGet STM
GET/api/agents/:name/memory/ltmSearch LTM
POST/api/agents/:name/memory/ltmAdd to LTM
DELETE/api/agents/:name/memoryClear memory
POST/api/agents/:name/session/newNew session

Example: Search LTM ​

bash
curl -X POST http://localhost:17890/api/agents/default/memory/ltm/search \
  -H "Content-Type: application/json" \
  -d '{"query": "API discussion", "limit": 5}'

Example: Clear Memory ​

bash
curl -X DELETE http://localhost:17890/api/agents/default/memory

Memory Configuration ​

STM Window Size ​

Control how many turns to keep:

bash
moxxy run --agent default --prompt "Store '20' in vault as stm_window_size"

LTM Embedding Model ​

Configure the embedding model:

bash
moxxy run --agent default --prompt "Store 'text-embedding-3-small' in vault as embedding_model"

Memory Cleanup ​

Automatically prune old memories:

bash
moxxy run --agent default --prompt "Store '30' in vault as ltm_retention_days"

Best Practices ​

What to Store ​

Good for LTM:

  • Important facts
  • User preferences
  • Project context
  • Recurring patterns

Not for LTM:

  • Temporary calculations
  • Verbatim conversations
  • Ephemeral data

Session Management ​

  • New session for unrelated topics
  • Continue for related follow-ups
  • Clear when starting fresh

Memory Hygiene ​

Periodically review and clean:

bash
# View current memory
cat ~/.moxxy/agents/default/current.md

# Reset if needed
rm ~/.moxxy/agents/default/memory.db
moxxy agent restart default

Troubleshooting ​

Memory Not Persisting ​

  1. Check database permissions:

    bash
    ls -la ~/.moxxy/agents/default/memory.db

  2. Verify SQLite integrity:

    bash
    sqlite3 ~/.moxxy/agents/default/memory.db "PRAGMA integrity_check;"

Semantic Search Not Working ​

  1. Verify sqlite-vec extension:

    bash
    moxxy doctor

  2. Check embedding configuration:

    bash
    moxxy run --agent default --prompt "What embedding model am I using?"

Memory Growing Too Large ​

  1. Check database size:

    bash
    du -h ~/.moxxy/agents/default/memory.db

  2. Vacuum to reclaim space:

    bash
    sqlite3 ~/.moxxy/agents/default/memory.db "VACUUM;"

  3. Set retention policy in vault

Open source · Self-hosted · Data sovereign

© 2026 Moxxy. Built with Rust.