How MemoryCore Supports Memory Recall: Architecture and Implementation Guide

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, 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, 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, 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) 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) 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, with granular metrics tracked in 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. This classification allows the API layer (exposed through 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:

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:

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:

{
  "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 orchestrates query construction, hybrid vector/FTS retrieval, and result deduplication.
• Storage backends include SQLite-based vector stores (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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}