<!-- source: https://deepwiki.com/openclaw/openclaw/3.4.3-memory-and-search -->

# Memory & Search

- extensions/acpx/src/process-reaper.test.ts
- extensions/acpx/src/process-reaper.ts
- extensions/diffs-language-pack/npm-shrinkwrap.json
- extensions/diffs-language-pack/package.json
- extensions/memory-core/src/dreaming-phases.test.ts
- extensions/memory-core/src/memory/index.test.ts
- extensions/memory-core/src/memory/manager-embedding-errors.ts
- extensions/memory-core/src/memory/manager-embedding-ops.ts
- extensions/memory-core/src/memory/manager-embedding-policy.test.ts
- extensions/memory-core/src/memory/manager-embedding-policy.ts
- extensions/memory-core/src/memory/manager-embedding-timeout.test.ts
- extensions/memory-core/src/memory/manager-local-worker-errors.ts
- extensions/memory-core/src/memory/manager-provider-state.ts
- extensions/memory-core/src/memory/manager-session-sync-state.test.ts
- extensions/memory-core/src/memory/manager-session-sync-state.ts
- extensions/memory-core/src/memory/manager-source-state.test.ts
- extensions/memory-core/src/memory/manager-source-state.ts
- extensions/memory-core/src/memory/manager-sync-ops.archive-delta-bypass.test.ts
- extensions/memory-core/src/memory/manager-sync-ops.interval.test.ts
- extensions/memory-core/src/memory/manager-sync-ops.startup-catchup.test.ts
- extensions/memory-core/src/memory/manager-sync-ops.ts
- extensions/memory-core/src/memory/manager-sync-yield.test.ts
- extensions/memory-core/src/memory/manager.fts-only-reindex.test.ts
- extensions/memory-core/src/memory/manager.ts
- extensions/memory-core/src/memory/manager.watcher-config.test.ts
- extensions/memory-core/src/memory/qmd-manager.test.ts
- extensions/memory-core/src/memory/qmd-manager.ts
- extensions/memory-core/src/memory/watch-settle.ts
- extensions/memory-lancedb/index.test.ts
- extensions/memory-lancedb/index.ts
- extensions/memory-lancedb/package.json
- extensions/qa-matrix/src/cli.runtime.test.ts
- extensions/telegram/src/api-fetch.test.ts
- extensions/telegram/src/send.test-harness.ts
- extensions/voice-call/src/cli.test.ts
- extensions/voice-call/src/cli.ts
- extensions/voice-call/src/gateway-continue-operation.test.ts
- extensions/voice-call/src/gateway-continue-operation.ts
- packages/gateway-protocol/src/schema/agents-models-skills.test.ts
- packages/memory-host-sdk/src/host/embeddings.test.ts
- packages/memory-host-sdk/src/host/embeddings.ts
- packages/memory-host-sdk/src/host/embeddings.types.ts
- scripts/lib/official-external-plugin-catalog.json
- scripts/lib/plugin-sdk-doc-metadata.ts
- src/agents/agent-bundle-mcp-materialize.ts
- src/agents/agent-bundle-mcp-runtime.test.ts
- src/agents/agent-bundle-mcp-runtime.ts
- src/agents/agent-bundle-mcp-tools.materialize.test.ts
- src/agents/agent-bundle-mcp-types.ts
- src/agents/agent-tools-agent-config.exec.test.ts
- src/agents/agent-tools.ts
- src/agents/embedded-agent-runner/compact.hooks.test.ts
- src/agents/embedded-agent-runner/compact.queued.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.test.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.ts
- src/agents/embedded-agent-runner/effective-tool-policy.ts
- src/agents/embedded-agent-runner/run/attempt.prompt-helpers.ts
- src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts
- src/agents/tool-policy-audit.ts
- src/agents/tool-policy-pipeline.test.ts
- src/agents/tool-policy-pipeline.ts
- src/agents/tools-effective-inventory.test.ts
- src/auto-reply/envelope.test.ts
- src/auto-reply/envelope.ts
- src/auto-reply/reply/agent-runner-memory.test.ts
- src/auto-reply/reply/agent-runner-memory.ts
- src/auto-reply/reply/commands-export-session.test.ts
- src/auto-reply/reply/commands-export-session.ts
- src/auto-reply/reply/mentions.test.ts
- src/auto-reply/reply/mentions.ts
- src/cli/mcp-cli.test.ts
- src/cli/mcp-cli.ts
- src/commands/doctor/shared/active-tool-schema-warnings.test.ts
- src/commands/doctor/shared/active-tool-schema-warnings.ts
- src/config/mcp-config.ts
- src/config/sessions.ts
- src/config/sessions/session-file-rotation.ts
- src/config/sessions/store-entry-shape.ts
- src/flows/doctor-core-checks.runtime-errors.test.ts
- src/flows/doctor-core-checks.runtime.test.ts
- src/flows/doctor-core-checks.runtime.ts
- src/gateway/server.sessions.reset-models.test.ts
- src/plugins/memory-embedding-providers.ts
- src/plugins/official-external-plugin-catalog.test.ts

This page documents the memory system within the agent runtime. It covers the `MemoryIndexManager` and `QmdMemoryManager` lifecycles, hybrid search (vector + FTS), synchronization strategies, and the background "dreaming" system for long-term memory promotion.

## Architecture Overview

The memory system indexes Markdown files from the agent workspace and session transcripts into a storage backend (SQLite or LanceDB) with vector embeddings and full-text search capabilities. Agents interact with indexed memory via primary tools:

- memory_search - semantic search over indexed chunks extensions/memory-core/src/memory/qmd-manager.ts 27-30
- memory_get - targeted read of specific files or line ranges extensions/memory-core/src/memory/qmd-manager.ts 34-38
- memory_recall - vector search specific to the active-memory backend extensions/memory-lancedb/index.ts 143-150

### Memory System Data Flow

The system bridges unstructured natural language files into a structured "Code Entity Space" for efficient retrieval.

Title: Memory Indexing and Search Pipeline

```

```

Sources: [extensions/memory-lancedb/index.ts198-211](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L198-L211) [extensions/memory-core/src/memory/qmd-manager.ts110-120](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L110-L120) [extensions/memory-core/src/memory/qmd-manager.ts168-172](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L168-L172) [extensions/memory-lancedb/index.ts143-150](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L143-L150)

## Memory Managers

OpenClaw supports two primary memory management backends: the builtin SQLite/LanceDB-based engine and the high-performance QMD (Quasi-Memory Daemon).

### MemoryIndexManager (Builtin)

The builtin manager handles file watching and indexing.

- File Watchers : Monitors MEMORY.md , the memory/ directory, and session files extensions/memory-core/src/memory/qmd-manager.ts 110-120
- Filtering : Ignores non-markdown churn such as .git , node_modules , and vendor directories extensions/memory-core/src/memory/qmd-manager.ts 92-104
- Hybrid Search : Combines vector scores with keyword matches; uses over-fetching to handle "envelope sludge" (contaminated memories) extensions/memory-lancedb/index.ts 203-211

### QmdMemoryManager

The `QmdMemoryManager` manages the QMD backend, which uses `mcporter` for background indexing and data synchronization [extensions/memory-core/src/memory/qmd-manager.ts149-154](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L149-L154)

- Lifecycle : Supports background sync via QmdEmbedQueueState to manage sequential heavy ML work extensions/memory-core/src/memory/qmd-manager.ts 156-160
- Process Management : Spawns mcporter with specific timeouts and retry logic using withFileLock to prevent SQLITE_BUSY errors extensions/memory-core/src/memory/qmd-manager.ts 217-221
- QMD Format : Leverages buildSessionEntry and parseQmdQueryJson for cross-platform memory compatibility extensions/memory-core/src/memory/qmd-manager.ts 22-32

Sources: [extensions/memory-core/src/memory/qmd-manager.ts92-120](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L92-L120) [extensions/memory-lancedb/index.ts203-211](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L203-L211) [extensions/memory-core/src/memory/qmd-manager.ts156-160](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L156-L160)

## Embedding Providers

Embedding provider resolution follows a strict hierarchy defined in `resolveMemoryBackendConfig`.

### Provider Selection

1. OpenAI : Primary remote provider for high-quality embeddings like text-embedding-3-small extensions/memory-lancedb/index.ts 40-42
2. Global Registry : Providers are managed via a global registry using MEMORY_EMBEDDING_PROVIDERS_KEY to ensure consistency across the agent runtime extensions/memory-core/src/memory/qmd-manager.test.ts 211-213

Sources: [extensions/memory-lancedb/index.ts40-42](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L40-L42) [extensions/memory-core/src/memory/qmd-manager.test.ts211-213](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.test.ts#L211-L213)

## Dreaming & Memory Promotion

### Dreaming System

Dreaming is the process of background multi-agent memory sweeps that promote "short-term" candidates into long-term durable storage.

- Phases : Includes light (frequent lookbacks) and rem (narrative synthesis) extensions/memory-core/src/dreaming-phases.ts 16-18
- Memory Flush : Triggered when the context window reaches a threshold. resolveMemoryFlushPlan determines what needs to be archived src/auto-reply/reply/agent-runner-memory.ts 39
- QMD Storage : Long-term memories are written to the workspace in QMD-compatible formats, typically under memory/YYYY-MM-DD.md src/auto-reply/reply/agent-runner-memory.test.ts 159-166

### Short-Term Promotion

The promotion pipeline tracks how often specific snippets are recalled during active sessions.

- Recalls : Tracked via recordShortTermRecalls which persists data to short-term-recall.json extensions/memory-core/src/dreaming-phases.test.ts 22-25
- Ranking : rankShortTermPromotionCandidates uses signal counts to determine which snippets deserve promotion extensions/memory-core/src/dreaming-phases.test.ts 21

Sources: [extensions/memory-core/src/dreaming-phases.ts16-18](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/dreaming-phases.ts#L16-L18) [src/auto-reply/reply/agent-runner-memory.ts39](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L39-L39) [extensions/memory-core/src/dreaming-phases.test.ts21-25](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/dreaming-phases.test.ts#L21-L25)

## Session Compaction & Memory Flush

When a session grows too large, the system performs compaction.

- Preflight Compaction : A guardrail run before the main agent execution if the token count is high src/auto-reply/reply/agent-runner-memory.ts 55
- Memory Flush : If the session is nearing the model's limit, runMemoryFlushIfNeeded invokes an agent to summarize the conversation into a permanent file src/auto-reply/reply/agent-runner-memory.ts 15-18
- Target Safety : ensureMemoryFlushTargetFile ensures that memory files are only written within the agent's designated workspace src/auto-reply/reply/agent-runner-memory.ts 93-115

Sources: [src/auto-reply/reply/agent-runner-memory.ts15-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L15-L115)

## Bridging "Natural Language Space" to "Code Entity Space"

### Diagram 1: Memory Tools and Implementation

Title: Association of Tool Names to Code Entities

```

```

Sources: [extensions/memory-core/src/memory/qmd-manager.ts27-51](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/memory/qmd-manager.ts#L27-L51) [extensions/memory-lancedb/index.ts143-150](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L143-L150) [extensions/memory-lancedb/index.ts198-211](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-lancedb/index.ts#L198-L211)

### Diagram 2: Dreaming and Promotion Flow

Title: From Conversation to Long-Term Memory

```

```

Sources: [src/auto-reply/reply/agent-runner-memory.ts15-18](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L15-L18) [extensions/memory-core/src/dreaming-phases.ts16-18](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/dreaming-phases.ts#L16-L18) [extensions/memory-core/src/dreaming-phases.test.ts21-25](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/memory-core/src/dreaming-phases.test.ts#L21-L25)
