Agent Memory Errors Handbook: Cases 91–95

This installment is part of the Agent Memory Errors: 100 Cases Handbook series.

Case 91: Memory Architecture & System Design Errors — Monolithic Memory Bottleneck Scaling

Scenario

All the Agent’s memories (short-term, long-term, episodic, semantic) are stored in a single database instance. As user volume grows, the database’s CPU and I/O reach limits, and query latency increases from 50 ms to 2 s.

Error Manifestation

Agent response time significantly increases, user experience degrades. During peak times connection pools are exhausted and requests timeout and fail.

Solution

1. Memory-tiered architecture: short-term memory uses Redis (in-memory), long-term memory uses vector database, semantic memory uses graph database
2. Implement user sharding for long-term memory: shard by user ID hash to multiple database instances
3. Introduce read-write separation: writes go to master, reads go to replicas, reducing master pressure

Principle

Different memory types have different access patterns and consistency requirements. Monolithic architecture cannot meet diverse performance needs. Tiering and sharding are inevitable choices for scaling.

Case 92: Memory Architecture & System Design Errors — Memory Tier Migration Data Loss

Scenario

The system architecture automatically migrates short-term memories older than 30 days to long-term memory. The migration script converts short-term memory JSON format to long-term memory vector format. But the “user emotion tag” field in JSON has no corresponding field in the long-term memory schema and is discarded.

Error Manifestation

When the user queries early conversations, the Agent cannot perceive the emotional context at the time, and replies lack empathy. Emotion analysis reports show missing emotion data for early conversations.

Solution

1. Perform schema mapping validation before migration: identify fields in source schema not in target schema, triggering human review or automatic mapping
2. Use schema evolution strategy: target schema supports “extension fields”; unknown fields are preserved as JSON blob
3. Perform data integrity audit after migration: sample check consistency of key fields before and after migration

Principle

Data migration is a high-risk part of system engineering. Schema incompatibility causes silent data loss. Strict pre-migration checks and post-migration audits are necessary quality assurance.

Case 93: Memory Architecture & System Design Errors — Backup Restore Point Inconsistency

Scenario

During system backup, the vector database backup time is T1, and the relational database backup time is T2 (T2 > T1). During restore, the vector database is restored to T1 state, and the relational database is restored to T2 state. A certain memory was updated between T1 and T2: the vector representation changed, but metadata in the relational database is still old.

Error Manifestation

When the Agent retrieves this memory, vector and metadata do not match (e.g., vector represents “likes A” while metadata records “likes B”), causing confused output.

Solution

1. Implement consistent snapshots: pause writes during backup or use distributed snapshots (e.g., MySQL’s FLUSH TABLES WITH READ LOCK)
2. Record “backup timestamps”: during restore check backup times of each component; trigger alerts or manual alignment when inconsistent
3. Use changelog: after restore, replay logs to synchronize all components to the same point in time

Principle

Backups of multi-component systems without global consistency guarantees enter logically impossible states after restore. Distributed transactions and global snapshots are standard solutions.

Case 94: Memory Architecture & System Design Errors — Memory Garbage Collection Overhead

Scenario

The Agent implements automatic garbage collection: clean expired memories monthly. The GC process needs to scan all memory records to check expiration times. As memory data grows to 100 million records, the GC process takes 6 hours, during which CPU and I/O spike, affecting normal queries.

Error Manifestation

During GC, Agent response latency increases 10x; users complain the system is “laggy.” Operations are forced to manually trigger GC during low-traffic periods.

Solution

1. Change GC to incremental: clean only a small batch (e.g., 10,000 records) each time, spread across multiple small tasks
2. Use TTL indexes: rely on database automatic expiration mechanisms (e.g., Redis expire, MongoDB TTL index) rather than application-layer scanning
3. Partition memory for divide-and-conquer: clean by time partition, only cleaning oldest partitions, avoiding full table scans

Principle

Garbage collection is necessary, but implementation determines system impact. Full-scan GC is unsustainable at large data volumes. Leveraging database-native capabilities and incremental strategies is better design.

Case 95: Memory Architecture & System Design Errors — Schema Evolution Memory Corruption

Scenario

The Agent memory JSON schema evolves from v1 to v2: in v1 “user preference” is a string, in v2 it’s changed to an object ({"theme": "dark", "language": "zh"}). The system does not migrate old data, and new code parses old data as v2.

Error Manifestation

Parsing old memory throws exceptions; the Agent cannot read users’ old preference settings and falls back to defaults. Logs are full of JSON parsing errors.

Solution

1. Implement schema version control: each memory record stores its schema version number; choose corresponding parsing logic by version number during parsing
2. Read-time migration: automatically convert old-version data to latest version when reading
3. Write-time forced upgrade: check data version when writing; old-version data is upgraded before writing

Principle

Schema evolution is an inevitable requirement for long-running systems. Systems without version management face the dilemma of “old data cannot be parsed” after schema changes.

Source: Agent Search