Memory

SwarmClaw provides persistent memory for agents using a hybrid search system combining keyword matching and semantic embeddings.

Storage

Memories are stored in a SQLite database (data/memory.db) with FTS5 full-text search indexing. Each memory has:

• Title — Short label for the memory
• Content — Full text content
• Agent — Which agent owns this memory
• Tags — Optional categorization tags
• Embedding — Optional vector embedding for semantic search

Hybrid Search

When you search agent memory, SwarmClaw runs two searches in parallel:

1. FTS5 keyword search — Fast exact and prefix matching using SQLite's full-text search engine
2. Vector similarity search — Cosine similarity against stored embeddings (if configured)

Results from both searches are merged and deduplicated, giving you the best of both approaches: exact matches for specific terms and semantic matches for related concepts.

Embeddings

To enable semantic search, configure an embedding provider in Settings.

Supported Providers

Configuration

1. Go to Settings in the sidebar
2. Under Embeddings, select a provider
3. Choose a model (or use the default)
4. If using OpenAI, select a credential with an API key
5. Save

New memories will automatically get embeddings. Existing memories without embeddings still work via FTS5 keyword search.

Query Expansion

When an agent searches memory, SwarmClaw can automatically expand the query into semantic variants using LLM generation. For example, a search for "deployment process" might also search for "deploy workflow", "release pipeline", and "shipping to production". This improves recall by matching memories that use different terminology for the same concept.

Query expansion runs automatically when a default agent with an LLM provider is configured. It falls back to a single query if no provider is available.

MMR (Maximal Marginal Relevance)

Search results are re-ranked using MMR to balance relevance against diversity. This prevents the top results from being near-duplicates — instead, you get a mix of the most relevant and most distinct matches.

The lambda parameter (default 0.5) controls the trade-off: higher values favor relevance, lower values favor diversity.

Memory Graph

Memories can be linked to form a knowledge graph. When retrieving a memory with depth > 0, SwarmClaw traverses linked memories up to the configured depth limit, returning a connected subgraph of related context.

An interactive Memory Graph visualization is available in the Memory browser, showing a force-directed node-link diagram of memory connections. Click any node to view its details.

API: GET /api/memory/graph?agentId=<id>&limit=<n> returns { nodes, links } for rendering.

Cross-Agent Memory Scope

By default, agents only see their own memories. Use the scope parameter to control visibility:

Cross-agent search (scope: all) is especially useful for delegation-heavy agents gathering context from other agents' work.

Pinned Memories

Mark a memory as pinned: true to always preload it into the agent's context at the start of every run. Useful for critical facts, standing instructions, or identity-defining context.

Memory Categories

Agents categorize memories into structured buckets. When storing a memory, the agent picks the best-fit category from:

Category aliases are normalized automatically — for example, contacts maps to identity/contacts, routine maps to identity/routines.

Memory Sharing

Use sharedWith: ["agent-id-1", "agent-id-2"] when storing a memory to share it with specific agents. Those agents can read the memory in their context without it being fully public.

Connector Contact Resolution

When a message arrives via a connector (WhatsApp, Discord, etc.), SwarmClaw automatically resolves the sender against stored contact memories.

The system collects all available sender identifiers (phone JIDs, platform user IDs, alternate IDs) and normalizes phone numbers for matching — stripping country code formatting, converting local numbers (e.g., 076... to 4476...), and comparing digit suffixes.

If a match is found, a Known Sender context block is injected into the agent's prompt, giving the agent immediate awareness of who is messaging.

Memory Visibility (QMD Scope)

Identity memories (identity/* categories) and contact resolution are private by default:

• DMs / peer chats: Full injection — identity memories, contact resolution, known sender block
• Group chats: Identity memories and contact resolution are suppressed to prevent leaking personal information

Pinned memories and relevance-based search results are visible in all contexts.

Knowledge Base

Separate from per-agent memories, the Knowledge surface is the shared source library for reference material, ingestion, grounding, and citations.

Use knowledge when you want:

• manual text, file, or URL sources shared across agents
• grounding and citation persistence on chats or structured runs
• source lifecycle management (sync, archive, restore, supersede)
• hygiene workflows for stale, duplicate, overlapping, or broken sources

Per-Agent Memory

Each agent has its own memory space. Memories created during a chat are tagged with the agent ID. When an agent searches memory, it only sees its own memories (unless using cross-agent scope).

API

Memory is managed through the agent's chat context. Agents with memory enabled can:

• Store new memories during conversations
• Search their memory for relevant context
• Update existing memories with new information
• Link / unlink related memories for graph-style traversal
• Attach references (files/URLs) and image assets
• Run maintenance (dedupe + prune) and consolidation workflows
• Track sources — source and sourceUrl fields on stored memories for provenance tracking (shown in search results)

Linked References & Attachments

Memories can include:

• references metadata (file paths, URLs, notes)
• imagePath assets stored under data/memory-images
• Linked memory IDs for graph traversal at retrieval time

This lets agents recover context chains, not just isolated notes.

Maintenance & Consolidation

SwarmClaw supports memory upkeep endpoints:

• GET /api/memory/maintenance to preview dedupe/prune candidates
• POST /api/memory/maintenance to execute cleanup (for example with ttlHours and maxDeletes)

The daemon also performs periodic consolidation so long-running agents keep a durable, compact memory trail.