From a Completed Turn to Layered Memory
In TencentDB Agent Memory, the important lifecycle question is not simply when a conversation is saved. It is what changes about that conversation as it becomes something a later Agent can use. This chapter follows one completed work turn from raw evidence through structured memories, scene documents, and profile-level context, so the reader can tell what each layer preserves, what each transition costs, and why a useful memory may not be available immediately.
The four layers are best understood as different views of the same history. L0 protects the evidence of what was said. L1 decides which parts are durable enough to describe as facts, events, preferences, instructions, or work knowledge. L2 groups related records into a scene that has continuity rather than a pile of isolated entries. L3 compresses scenes into a higher-level profile or operating memory that helps an Agent orient itself quickly. Moving upward is not a march toward perfect truth. It is a sequence of increasingly selective representations.
L0 preserves the evidence; L1 makes a decision
A completed turn enters the system through capture, not through an immediate request to an LLM to summarize everything. The L0 recorder receives the host’s conversation messages, selects the user and assistant material that belongs to the turn, sanitizes injected tags, removes content that is not useful for memory, and writes a flat record. In the local design, the persistent representation is JSONL: one message per line, daily files, with session information stored as fields. That shape is deliberately plain. It is easy to append, stream, inspect, and recover without treating a filename as the identity of a conversation.
“Raw” therefore means raw evidence within a capture boundary, not an untouched dump of every byte the Agent saw. The recorder excludes noise because the prompt sent to an Agent often contains more than the user’s real request. Harness metadata, system reminders, generated wrappers, and long assistant code blocks can dominate search terms without helping a future Agent understand the work. The Proxy applies a related rule before writing through the remote path: it extracts the actual user query from the last user message instead of storing the entire harness envelope as if it were intent.
Capture is incremental. A session may send its full history at the end of every turn, so the recorder needs to know what has already been written. TencentDB Agent Memory uses two protections: a position slice based on the message count known before prompt construction, and a timestamp cursor that keeps only newer messages. The position slice is useful when timestamps drift or are missing; the timestamp cursor is a fallback across restarts. The read-cursor-write sequence is protected by an atomic checkpoint operation so two concurrent end-of-turn events do not both observe the same old cursor and duplicate the batch.
This first transition has a practical consequence: L0 can succeed even when later processing fails. If the vector index is unavailable, or an embedding request fails, the conversation record can still be retained. The indexing path is secondary to preservation. On SQLite-style storage, metadata and full-text indexing can be written quickly while embeddings are computed in the background. On a remote vector backend, embedding may be supplied synchronously or handled by the server. In either case, a failure in the acceleration path should not erase the evidence that the turn happened.
L1 is where selectivity begins. The extractor first applies a stricter quality gate than L0. Short, noisy, transient, or otherwise unsuitable messages can remain in the raw conversation while being excluded from structured memory. The extractor then sends a bounded set of recent messages, with a small amount of older context to resolve continuity, to an LLM. The output is expected to be a scene-segmented JSON array: each scene names a message range and contains memories tied to source message identifiers.
That source linkage matters because a structured sentence can look more certain than the conversation that produced it. A record such as “the team chose option B” should be traceable to the messages that actually confirm the choice. The extraction rules distinguish an explicit decision from a suggestion, a durable instruction from a one-time request, and a factual event from a passing feeling. A memory must stand on its own rather than relying on phrases such as “that thing above.” The system also keeps type and priority information so later stages can decide how a record should be combined or emphasized.
The exact types depend on the configured prompt family. In chat-oriented extraction, the supported categories include persona, episodic events, and instructions. In the work-oriented prompt, the categories instead emphasize work facts, work tasks, work methods, and work artifacts. The second set is not just a renamed version of the first. It is designed for shared team use: it asks whether a piece of information can help a teammate or Agent continue a project, and it warns against converting personal or private details into team memory. This is one of the clearest places where extraction rules encode a boundary, not merely a format.
An LLM can also return a legitimate empty result. The system preserves scene segmentation even when no memory qualifies, and it records diagnostic reasons for empty paths such as no usable JSON, parse failure, or no meaningful memories. This avoids conflating “the conversation contained nothing durable” with “the extraction service broke.” Neither outcome guarantees that a later Agent will see new context, but they imply different operational responses.
After extraction, L1 conflict handling prevents every new sentence from becoming another permanent duplicate. The process has two phases. First, each new candidate is compared with a small set of existing records. If the store provides native hybrid search, the system can use it; otherwise keyword search and client-side vector search run in parallel and their ranked lists are combined with Reciprocal Rank Fusion. RRF rewards records that appear near the top of more than one list. It is a way to combine retrieval signals, not a probability that a memory is true.
Second, a batch LLM judgment chooses what to do with the candidates. A new record can be stored, an existing record can be updated, related records can be merged, or a candidate can be skipped. The choice is scoped to the relevant isolation context during extraction, so a new fact does not resolve a conflict by comparing itself with another tenant’s data. If no retrieval capability exists, no similar records are found, or conflict judgment fails, the fallback is to store the candidates as new records. That choice favors retaining potentially useful evidence over making an aggressive and irreversible deletion decision.
Updates and merges reveal the difference between the retrieval view and the history view. The old target records are removed from the live vector store so a search does not return both the old and the new formulation. The append-only JSONL record remains until periodic cleanup reconciles it with the current retrieval state. The result is a materialized view: fast search sees the current form, while the persistent append history helps with recovery and provenance.
The diagram shows why “the turn was captured” and “the Agent’s profile was updated” are different statements. Several queued transitions can intervene, and each one has its own inputs, failure behavior, and representation.
L2 and L3 compress context on a schedule
L2 takes the current L1 records and organizes them into scene blocks. A scene is intended to be a coherent narrative document about a related project, goal, problem, or pattern, not a list with a new bullet appended for every record. The scene extractor receives new memories, a map of existing scenes, and the current time. It may create a scene, update one, merge overlapping scenes, or rewrite a document so the new information fits the existing narrative.
The extractor’s operating boundary is deliberately narrow. Its tool-enabled LLM is sandboxed to the scene-block area; it cannot directly edit the checkpoint, scene index, or persona file. Deletion is represented by a marker that the engineering side later removes, and the index is synchronized after the LLM run. This arrangement separates judgment from bookkeeping. The LLM decides how a scene should change; the surrounding code decides how to clean soft deletes, rebuild the index, and preserve system files.
That boundary also explains why an L2 scene is not simply the next database row. It is a derived document with its own narrative choices. The prompt tells the extractor to prefer updating an existing related scene over creating another one, to merge similar scenes when the scene count approaches its limit, and to preserve an evolution trail when new information conflicts with old information. The output can be more useful for orientation than ten independent L1 sentences, but it can also omit detail or carry an interpretation that must be checked against the lower layer.
The pipeline therefore tracks more than whether an L2 call returned successfully. It compares the scene index and contents before and after extraction, synchronizes changed profiles back to a capable store, and records generation provenance linking L1 inputs to L2 outputs. If the LLM produces no file change, the checkpoint is not advanced as though a new scene had been created. A successful API call and a meaningful derived update are not the same event.
L3 is another change in scale. The persona generator reads the existing profile, identifies scenes changed since the previous generation, and asks an LLM to create or update the higher-level document. On an initial run, it can use all available scene material; on later runs, it focuses on scenes updated after the previous profile time. The generated result is sanitized, navigation metadata is rebuilt, and the final profile is written only after the system has a usable non-empty body.
The word persona can be misleading if it suggests an immutable psychological portrait. In chat mode, L3 is a long-term profile. In work mode, the same layer can represent a team operating doctrine. In both cases, it is a compressed, derived view of scene material. The system has recovery logic for a missing or empty profile, and it can trigger regeneration when an Agent explicitly requests it, when the first scene appears, after cold-start extraction, or when enough new memories have accumulated. Those triggers describe when a new synthesis is worth attempting; they do not certify the existing synthesis as correct.
The timing rules keep these transformations away from the foreground request. L1 can be triggered when a session’s conversation count reaches its effective threshold, when the session becomes idle, or when the process shuts down. Warm-up mode begins with a small threshold and increases it after successful runs, allowing a new session to become useful quickly before settling into less frequent processing. If a session is active but below threshold, the idle timer provides a catch-up path rather than leaving a small tail forever.
L2 uses a different timer because it should respond to new L1 material without running continuously. After L1 completes, the desired L2 time can be advanced earlier, but not ahead of the minimum interval since the previous L2 run. After L2 completes, a maximum interval provides a later polling guarantee for active sessions. If a session has gone cold, the timer is cancelled instead of spending an LLM call on abandoned work. L3 follows L2 under a global concurrency guard so multiple scene updates do not trigger competing profile rewrites.
The scheduler’s queues make ownership of state explicit. Local operation keeps per-session state, timers, message buffers, and serial queues in process memory, with checkpoint persistence for restart recovery. During shutdown, it attempts a bounded flush, persists state even if the flush times out, and restores pending work when it starts again. In service operation, the repository provides a stateful manager that moves those responsibilities to an IStateBackend; timer scanners and workers can then coordinate across replicas with shared tasks and locks. The implementation details differ, but the lifecycle meaning remains: a turn can be durable before its abstractions are ready, and unfinished transitions must be recoverable rather than silently forgotten.
What is lost as the pipeline moves upward? L0 retains message-level wording and chronology, subject to capture sanitization. L1 loses much of the conversation’s incidental detail but gains type, priority, scene, and source references. L2 loses isolated phrasing in exchange for a coherent account of a project or situation. L3 loses still more detail in exchange for rapid orientation. That is why the layers cannot substitute for one another. When an Agent needs exact wording or a timeline, it should return to L0. When it needs a targeted fact, rule, or event, L1 is the more economical surface. When it needs a scene-level explanation, it can read L2. When it needs a quick starting context, L3 is the appropriate bootstrap.
A useful test follows from this lifecycle. If a later Agent does not remember a decision, ask where the failure occurred: was the message never captured, filtered out at L1, rejected or misclassified during conflict handling, not yet consolidated into a scene, excluded from the changed-scene set, or simply not retrieved? TencentDB Agent Memory makes those stages separate enough to inspect. It does not make them infallible. Layering improves the chance that experience can be reused because each representation has a defined job; it also makes freshness, provenance, and correction part of the memory problem itself.