Memory

ScalyClaw remembers. Not just within a conversation, but across all conversations, all channels, forever. Every interaction is an opportunity to learn something about the user — a preference, a fact, a relationship, a recurring topic. That knowledge accumulates over time in a persistent memory store and is automatically surfaced when it becomes relevant, making every future conversation smarter and more personal than the last.

Memory in ScalyClaw is not a list of chat logs. It is a structured, searchable store of extracted knowledge — discrete facts and observations that the LLM identifies and records during the course of normal conversation, then retrieves on demand without any user intervention.

How Memory Works

Memory operates entirely in the background. From the user's perspective, ScalyClaw simply seems to know things. Under the hood, two processes are running in every conversation: extraction and retrieval.

Extraction

During and after each conversation turn, the LLM evaluates the exchange for information worth preserving. This is not keyword matching or rule-based parsing — the model exercises judgment about what is meaningful, stable, and useful to remember. A user mentioning in passing that they work at Acme Corp is extracted as a fact. A user expressing frustration with verbose answers is extracted as a preference. Casual small talk that carries no durable information is discarded.

When the LLM decides something is worth saving, it calls the built-in memory_store tool with a structured payload: the type, the content phrased as a clear, retrievable statement, a confidence score between 0 and 1 reflecting how certain the extraction is, and optional tags and TTL.

Storage

Memory entries are stored in SQLite using bun:sqlite, the high-performance native SQLite driver bundled with Bun. Each entry is stored with its text content alongside a float32 vector embedding generated by the configured embedding model. Two indexes are maintained in parallel:

• sqlite-vec — a vector index for cosine similarity search. This is the primary retrieval path, used whenever an embedding model is configured and functional. It finds semantically similar memories even when the exact words do not match.
• FTS5 — SQLite's built-in full-text search index. This serves as the fallback when vector search is unavailable or returns insufficient results. It matches on exact words and common morphological variants.

Retrieval Flow

Every time a new message arrives, ScalyClaw runs a memory retrieval pass before constructing the system prompt for the LLM. The query used for retrieval is derived from the incoming message — or from a synthesis of the recent conversation context when more than one turn is available. The retrieval pipeline runs as follows:

1. The query text is embedded using the configured embedding model to produce a float32 vector.
2. sqlite-vec performs a cosine similarity search against all stored memory vectors, returning candidates ranked by distance.
3. If sqlite-vec returns fewer than the required number of results — or if the embedding model is unavailable — FTS5 full-text search runs as a fallback against the same query.
4. Results from both passes are merged, de-duplicated, and re-ranked by a combined score that weights cosine similarity and confidence together.
5. The top-K results are formatted and injected into the system prompt as a Memories section, giving the LLM explicit access to what it knows about the user before it generates a response.

Retrieval Pipeline at a Glance

Incoming message
       ↓
embed(query)  →  float32 vector
       ↓
sqlite-vec cosine search  →  ranked candidates
       ↓  (if insufficient results)
FTS5 full-text fallback   →  keyword candidates
       ↓
merge + deduplicate + re-rank
  score = α × cosine_sim + β × confidence
       ↓
top-K results  →  injected into system prompt

Memory Types

Every memory entry is tagged with a type that describes the nature of the information. The type informs how the LLM interprets and uses the memory, and it is also available as a filter in the dashboard memory browser.

Confidence scores are not static. The LLM may update a memory's confidence upward when new information corroborates it, or downward when the user contradicts or corrects a stored entry. Contradicted entries are not automatically deleted — they are updated with lower confidence and a note about the correction, preserving the history.

Memory Tools

The LLM has five built-in memory tools available at all times during conversation. These tools are called automatically — the user does not need to ask ScalyClaw to remember something, and the user does not need to know the tools exist. The LLM decides when to call them based on what it determines is worth preserving or retrieving.

memory_store

Saves a new memory entry to the store. The LLM calls this when it identifies information in the conversation that is worth preserving for future use. If an entry with very similar content already exists, the tool updates the existing entry and adjusts its confidence rather than creating a duplicate.

// Example tool call — storing a preference inferred from conversation
{
  "name": "memory_store",
  "arguments": {
    "content": "User prefers code examples in TypeScript over JavaScript.",
    "type": "preference",
    "tags": ["coding", "typescript"],
    "confidence": 0.85
  }
}

// Example tool call — storing a fact stated explicitly by the user
{
  "name": "memory_store",
  "arguments": {
    "content": "User works at Acme Corp as a senior backend engineer.",
    "type": "fact",
    "tags": ["work", "employment"],
    "confidence": 1.0
  }
}

memory_search

Queries the memory store on demand. While retrieval is automatic before every response, the LLM may call memory_search mid-conversation when the user asks a question that might be answered from memory, or when the LLM wants to double-check what it knows before making a claim.

// Example tool call — searching for information about the user's work situation
{
  "name": "memory_search",
  "arguments": {
    "query": "user employer job role company",
    "limit": 5
  }
}

// Example tool response — results returned to the LLM
{
  "results": [
    {
      "id": "mem_01j9x4kzb2f3",
      "type": "fact",
      "content": "User works at Acme Corp as a senior backend engineer.",
      "confidence": 1.0,
      "score": 0.94,
      "createdAt": "2026-01-15T09:22:41Z",
      "updatedAt": "2026-02-03T14:08:17Z"
    }
  ]
}

Tool Parameters

Memory Management

The dashboard Memory page gives you full visibility into everything ScalyClaw has learned. It is the canonical interface for reviewing, editing, and pruning the memory store.

Browsing Memories

The memory browser displays all stored entries in a sortable, filterable list. Each row shows the memory content, its type badge, confidence score, and timestamps for when it was created and last updated. You can:

• Search by keyword or phrase across all memory content — uses the same FTS5 index as the retrieval pipeline.
• Filter by type to view only facts, preferences, relationships, events, or analysis entries.
• Filter by confidence to surface high-confidence entries or to find uncertain inferences that may need review.
• Sort by creation date, last-updated date, or confidence score.

Manual Operations

All memory operations available to the LLM are also available to you directly in the dashboard:

Asking ScalyClaw to Forget

You do not need to visit the dashboard to remove a memory. If you tell ScalyClaw during any conversation "forget that I work at Acme Corp" or "please don't remember anything about my schedule", it will search for matching entries and call its internal memory_delete tool to remove them. The deletion takes effect immediately — the entries are gone from the store before the next conversation turn.

// Tool call issued by the LLM when user asks it to forget something
{
  "name": "memory_delete",
  "arguments": {
    "id": "mem_01j9x4kzb2f3"
  }
}

Export and Backup

The memory store is an ordinary SQLite database file on disk. You can back it up, copy it, or inspect it with any SQLite browser. The dashboard also provides an export function that serializes all entries to a JSON array, suitable for archiving or migrating to another ScalyClaw instance.