Persistent Vector Memory in deer-flow: Hybrid Retrieval and Performance Tuning for Long-Horizon Agents

The Memory Dilemma of Long-Horizon Agents

When we connected ByteDance's open-source framework deer-flow into multi-hour autonomous research pipelines, the core challenge was not task orchestration but semantic memory persistence under high concurrency. Agents running for over 90 minutes need to recall earlier decisions, avoid redundant API calls, and maintain contextual continuity across sandbox restarts.

Most agent frameworks treat memory as an auxiliary feature, whereas deer-flow takes the problem seriously through pluggable memory backends. But integrating it into our existing PostgreSQL + pgvector stack exposed real architectural friction points.

deer-flow's Memory Chain Architecture

deer-flow splits memory into three layers:

1. Session buffer (ephemeral, in-process)
2. Vector store (semantic retrieval via embeddings)
3. Relational metadata (timestamps, task IDs, lineage)

The key insight is that hybrid search must fuse vector similarity, temporal recency, and task-ancestor filters. Pure cosine similarity retrieves semantically relevant memories but ignores causal order—which is exactly the most fatal flaw in long-horizon tasks.

Deliverable One: PostgreSQL Schema and HNSW Index

Below is our battle-tested schema that connects deer-flow's memory interface to pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE agent_memories (
  id BIGSERIAL PRIMARY KEY,
  agent_id TEXT NOT NULL,
  task_id TEXT NOT NULL,
  content TEXT NOT NULL,
  embedding vector(1536) NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  parent_task_id TEXT
);

-- HNSW index: sub-100ms vector search at 100K+ rows
CREATE INDEX ON agent_memories 
  USING hnsw (embedding vector_cosine_ops) 
  WITH (m = 16, ef_construction = 64);

-- Composite index for filtered vector search
CREATE INDEX ON agent_memories (agent_id, task_id, created_at DESC);

Key tuning lesson: with m set to 16 and ef_construction set to 64, we achieved a p99 latency of 12ms under 500 concurrent inserts. pgvector's default settings caused insert stalls exceeding 2 seconds during bulk memory writes—a pit we fell into deeply.

HNSW (Hierarchical Navigable Small World) is an approximate nearest neighbor search algorithm based on a multi-layer graph structure, widely used in vector databases. Its core idea is to organize vectors into a multi-layer navigable graph by distance: upper layers are sparse and used for fast cross-region jumps, while lower layers are dense and used for fine localization. Queries start from the top-layer entry point and greedily descend layer by layer, approaching the target vector with logarithmic complexity. pgvector's HNSW index controls build quality through two parameters, m and ef_construction: m is the number of neighbor edges retained per node in the graph—larger values improve graph connectivity and recall, at the cost of larger index size and memory overhead; ef_construction is the size of the candidate queue during construction—larger values slow construction but yield better index quality. Together they determine the recall-latency trade-off at query time, so production environments need repeated empirical tuning based on data scale and concurrent write patterns rather than sticking with defaults.

Deliverable Two: Hybrid Search Based on Reciprocal Rank Fusion

Pure vector search fails in complex multi-step tasks—the agent retrieves memories semantically relevant from 3 hours ago while ignoring a critical decision made 10 minutes ago.

We chose RRF over simple weighted summation because the latter fails catastrophically when vector scores cluster in the 0.85–0.90 range, completely drowning out the temporal recency signal. RRF's rank-based scoring mechanism is far more stable.

deer-flow's memory interface connects to our HybridMemoryRetriever, whose core logic is to separately obtain vector similarity rankings and temporal recency rankings, then fuse them with 1 / (k + rank) (k=60). Each sub-query takes the top 20, and the fused result returns the top 5.

This dual-channel design ensures that semantically relevant memories are not discarded due to age, and critical recent decisions are not ignored due to slightly lower vector scores.

RRF (Reciprocal Rank Fusion) is a parameter-free method for fusing results from multiple retrieval paths, first proposed by Cormack et al. in the information retrieval field. Its formula sums 1 / (k + rank_i) for each candidate document across all retrieval channels, where rank_i is the document's rank in the i-th channel and k is a smoothing constant (commonly 60). RRF's key advantage is that it relies only on ranks rather than raw scores, making it naturally immune to inconsistent score scales across channels—for example, vector cosine similarity and temporal recency typically fall in different ranges. Compared to weighted summation, RRF requires no per-channel tuning and will not let one channel's score concentration invalidate other signals. The cost is losing absolute score information—e.g., it cannot distinguish "extremely similar" from "moderately similar"—but for scenarios like long-horizon agent memory retrieval that require robust multi-signal fusion, rank-level fusion is generally more reliable.

Three Pitfalls in Production Integration

Missing embedding normalization: deer-flow does not enforce L2 normalization, and we observed a 22% drop in recall until we manually added a normalization function. This is an easily overlooked detail with an outsized impact.

Concurrent write bottleneck: the HNSW index locks the table during bulk inserts, causing write stalls of over 5 seconds. Our solution was to batch memory writes with INSERT ... ON CONFLICT DO NOTHING, while introducing a 50ms debounce window.

Embedding generation becomes the bottleneck: when testing multi-provider fallback latency through a third-party relay gateway, text-embedding-3-small averaged 127ms generation time, slower than the database write. We recommend pre-generating embeddings asynchronously to avoid blocking the memory write path.

Embedding normalization: L2 normalization of vector embeddings means dividing each vector by its Euclidean norm so that its length becomes 1. After normalization, the vector dot product is equivalent to cosine similarity, whereas unnormalized dot products between vectors of different lengths produce systematic bias due to magnitude differences—longer vectors are more likely to score higher. Different embedding models have no unified convention on whether to output normalized vectors, and frameworks like deer-flow do not enforce checks. If vectors are not normalized while the index is built for cosine similarity, retrieval ranking will be biased, manifesting as reduced recall. The fix is to normalize immediately after generating embeddings and persist the normalized vectors, while ensuring that writes and queries use the same normalization logic to avoid inconsistent vector distributions within the index.

Operational Trade-offs

deer-flow's pluggable memory abstraction makes swapping PostgreSQL for Qdrant very easy, and the lineage tracking supported by parent_task_id also lets us implement causal retrieval filters. The clean separation between the ephemeral buffer and persistent storage is equally commendable.

But the pain points are also obvious. The framework has no built-in memory compression mechanism, and our agents can reach 50K+ rows per session, causing index bloat. There is no automatic embedding cache invalidation when upstream models change, requiring external handling. Hybrid search logic can only be written at the application layer rather than being natively supported by the framework—meaning you have to rewrite this part every time you switch storage backends.

Embedding cache invalidation: embedding caches typically store vector results keyed by "text content hash + model identifier" to save API calls and latency from repeated generation. But when the upstream embedding model is upgraded, replaced, or deprecated, old and new vectors live in different semantic spaces. If the cache key does not include the model version, vectors from different spaces will be mixed during retrieval, causing semantic drift that is hard to diagnose. Therefore, cache design should incorporate the model name, version number, and even key parameters into the cache key, and proactively invalidate or version-isolate relevant caches when models change. This mechanism must be implemented at the application layer, because most agent frameworks and vector databases do not automatically track embedding provenance—without it, a single model migration could require a full vector rebuild accompanied by hidden retrieval quality degradation.

An Unsolved Open Question: When Should Agents Forget?

Our biggest unresolved dilemma is: when should an agent forget? Unbounded memory growth severely degrades performance after 6-hour sessions. Naive LRU eviction breaks causal chains. Time-decay scoring helps, but introduces new failure modes during context switches.

This is a question worth the entire community discussing together—how do you balance memory retention and retrieval performance in your long-horizon production systems?

One-line Summary

Tuning lessons and the forgetting problem for pgvector-based hybrid memory when long-horizon agents integrate with deer-flow.

Paragraph Summary

The article shares production practices for connecting the memory architecture of ByteDance's open-source framework deer-flow to PostgreSQL + pgvector. The author notes that the core challenge for long-horizon agents is semantic memory persistence under high concurrency, necessitating hybrid search that fuses semantic similarity, temporal recency, and task lineage. The article provides battle-tested table structures and HNSW index configurations (m=16, ef_construction=64), and argues that RRF outperforms weighted summation when vector scores cluster. Three pitfalls exposed in production integration are unnormalized embeddings causing a 22% recall drop, HNSW table locking during bulk writes, and embedding generation becoming a write bottleneck. Finally, the author notes that memory compression, cache invalidation, and forgetting strategies remain open challenges.