# How MemoryCore Supports Memory Recall: Architecture and Implementation Guide

> Discover how MemoryCore enhances memory recall with its layered retrieval pipeline. Explore vector search, FTS, and session filtering for efficient L1 memory surfacing before LLM prompt construction.

- Repository: [Tencent Cloud/TencentDB-Agent-Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
- Tags: architecture
- Published: 2026-08-24

---

**MemoryCore enables memory recall through a layered retrieval pipeline orchestrated by the `TdaiCore` class, combining vector similarity search, optional full-text search (FTS), and session-aware filtering to surface relevant L1 memories before LLM prompt construction.**

MemoryCore is the central memory management subsystem of the TencentDB-Agent-Memory repository, providing autonomous agents with persistent, contextually retrievable conversation history. Understanding how MemoryCore supports memory recall requires examining its coordinated flow from API entry points through storage backends to observability exporters.

## Core Recall Architecture

The recall process centers on the **`TdaiCore`** class, which exposes the primary interface for memory retrieval operations.

### Entry Point via handleBeforeRecall

In [`MemoryCore/src/tdai-core.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/tdai-core.ts), the **`handleBeforeRecall`** method serves as the main entry for all recall operations. When invoked—either by the HTTP gateway at `/recall` or via the OpenClaw "before-prompt-build" hook—this method first awaits store initialization, then delegates execution to `performAutoRecall`. Upon completion, it transmits latency and hit-count metrics through **`reportRecallMetrics`** to the telemetry pipeline.

### The performAutoRecall Engine

Located in [`MemoryCore/src/hooks/auto-recall.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/hooks/auto-recall.ts), **`performAutoRecall`** constructs the recall query by sanitizing user text and extracting keywords. It executes a hybrid retrieval strategy against the configured **`IMemoryStore`** interface, utilizing both vector similarity and optional FTS backends to retrieve top-K L1 memories. The engine applies **deduplication** logic and **session filtering** to eliminate redundant or internal-session entries before returning a structured `RecallResult` containing the retrieval strategy used (`keyword`, `vector`, or `skipped`) and any error information.

## Storage Backends and Retrieval Strategy

MemoryCore employs a dual-storage approach to ensure robust memory retrieval across diverse query types.

### Vector Store and Full-Text Search

The default vector storage implementation resides in [`MemoryCore/src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/sqlite.ts), providing SQLite-based persistence for vector embeddings. When configured, the system augments vector similarity searches with an optional FTS backend for keyword-based retrieval. If the FTS layer is unavailable, the system gracefully falls back to an in-memory scoring method to maintain operational continuity.

### Embedding Service Integration

When recall requires embedding the query text, the **`EmbeddingService`** (configured via `cfg.embedding` in [`MemoryCore/src/core/store/embedding.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/store/embedding.ts)) generates vector representations. This service supports delegation to remote providers or local execution models, with health status logged for operational visibility.

## Data Processing and Filtering

Retrieved memories undergo rigorous processing before inclusion in LLM contexts to ensure relevance and privacy.

### Deduplication and Session Isolation

The recall pipeline applies intelligent **deduplication** to remove redundant memory entries. Concurrently, **`SessionFilter`** (configured via `cfg.sessionFilter` in [`MemoryCore/src/utils/session-filter.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/utils/session-filter.ts)) excludes internal benchmark sessions from recall results. For multi-tenant deployments, checkpoint files maintain per-instance pipeline state, ensuring that concurrent recall operations do not interfere across isolated contexts.

## Observability and Error Resilience

MemoryCore implements comprehensive telemetry and structured error handling to maintain system reliability.

### Metrics and Distributed Tracing

Recall operations emit **OTLP spans** via [`MemoryCore/src/core/report/trace.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/report/trace.ts), with granular metrics tracked in [`MemoryCore/src/core/report/metric-tracking-recall.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/report/metric-tracking-recall.ts). The system records **recall latency**, **hit counts**, and **top similarity scores** to enable performance analysis and optimization of retrieval strategies.

### Structured Error Handling

Errors are wrapped using the **`RecallError`** taxonomy defined in [`MemoryCore/src/core/hooks/recall-errors.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/core/hooks/recall-errors.js). This classification allows the API layer (exposed through [`MemoryCore/src/gateway/server.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/MemoryCore/src/gateway/server.ts)) to return HTTP 200 responses with structured failure codes when recall operations fail, ensuring agent stability while surfacing diagnostic information.

## Practical Implementation Examples

### Direct API Integration

For plugin development or custom agent scripts, invoke recall directly through the core API:

```typescript
import { TdaiCore } from './MemoryCore/src/tdai-core.js';
import { OpenClawHostAdapter } from './MemoryCore/src/adapters/openclaw/host-adapter.js';

// Initialise core
const hostAdapter = new OpenClawHostAdapter({ api, pluginDataDir, config });
const core = new TdaiCore({ hostAdapter, config: parsedCfg });
await core.initialize();

// Perform a recall
const userQuery = "How do I reset my password?";
const sessionKey = "session-1234";
const recallResult = await core.handleBeforeRecall(userQuery, sessionKey);

console.log('Recall strategy:', recallResult.recallStrategy);
console.log('Top memories:', recallResult.recalledL1Memories);

```

### HTTP Gateway Endpoint

Client applications can trigger recall via the REST API exposed by the gateway:

```bash
curl -X POST https://gateway.example.com/tdai/recall \
  -H "Content-Type: application/json" \
  -d '{
        "user_text": "What is the quota for my storage?",
        "session_key": "sess-5678"
      }'

```

The endpoint returns a structured JSON response:

```json
{
  "code": 0,
  "recalledL1Memories": [
    { "content": "You have 100 GB of storage quota.", "score": 0.92, "type": "conversation" }
  ],
  "recallStrategy": "vector",
  "recallLatencyMs": 48,
  "hasError": false
}

```

## Summary

- **MemoryCore** implements memory recall through the `TdaiCore` class, exposing both programmatic APIs and HTTP endpoints for memory retrieval.
- The **`performAutoRecall`** engine in [`src/hooks/auto-recall.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/hooks/auto-recall.ts) orchestrates query construction, hybrid vector/FTS retrieval, and result deduplication.
- Storage backends include SQLite-based vector stores ([`src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/store/sqlite.ts)) with optional full-text search augmentation and configurable embedding services.
- **SessionFilter** and checkpoint mechanisms ensure multi-tenant isolation while internal sessions are excluded from retrieval results.
- Comprehensive observability through OTLP spans and the `metric-tracking-recall` module provides latency and accuracy metrics.
- Structured error handling via the `RecallError` taxonomy ensures graceful degradation without disrupting agent operations.

## Frequently Asked Questions

### What triggers MemoryCore to perform a memory recall?

MemoryCore triggers recall via the **`handleBeforeRecall`** method when the OpenClaw framework invokes the "before-prompt-build" hook, or when a client POSTs to the `/recall` HTTP endpoint. Both entry points perform a pre-fetch of relevant L1 memories before the LLM prompt is constructed, ensuring contextual continuity.

### How does MemoryCore handle recall failures?

According to the source code in [`src/core/hooks/recall-errors.js`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/hooks/recall-errors.js), errors are wrapped in a stable `RecallError` taxonomy. This allows the system to return HTTP 200 responses with structured failure codes and diagnostic information rather than throwing exceptions, ensuring the agent remains operational even when storage backends are temporarily unavailable.

### Can MemoryCore use only full-text search without vector similarity?

Yes, though the default configuration emphasizes vector similarity, the **`performAutoRecall`** engine supports multiple retrieval strategies. When the FTS backend is enabled in [`src/core/store/sqlite.ts`](https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/main/src/core/store/sqlite.ts) and vector similarity is insufficient, the system can rely primarily on keyword-based full-text search, falling back to in-memory scoring if necessary.

### What format do recalled memories return in?

Recalled memories return as **`RecallResult`** objects containing an array of `recalledL1Memories` with content, similarity scores, and memory types. The result also includes the `recallStrategy` employed (vector, keyword, or skipped), latency metrics, and error status flags, enabling downstream components to make informed decisions about context inclusion.