DEV Community: William Shi

Agent memory: where it lives, when it expires, how it is deleted

William Shi — Sun, 08 Nov 2026 12:35:30 +0000

You deleted the memory file. The agent still remembers.

That is the first thing worth knowing about agent memory: the file you can see is rarely the thing the model reads. Behind it sits an index, and an index outlives its source unless something deletes both.

Most writing about agent memory argues about retrieval quality. The questions that decide whether you can operate the system are duller: which store does the memory live in, what writes to it, when does it expire, and what is actually gone after a delete.

Three things get called memory

A context window, a session log and a knowledge base share one word and almost nothing else.

The context window is assembled per turn and discarded after. A session log is append-only and exists to reconstruct what happened. A knowledge base is durable, indexed and queried. Conflating them is how retention questions go unanswered: you delete "the memory", and you have deleted one of three.

When it is written, and what rebuilds it

Saving the memory file rebuilds the index. In one agent workbench I maintain, the file API calls a rebuild when the path is the memory file, and the rebuild re-reads the file and re-embeds what it finds.

The interesting part is the condition. The guard hashes the file first, and the hash helper returns an empty string when the file does not exist:

    def _get_file_hash(self) -> str:
        """Get MD5 hash of MEMORY.md."""
        if not self._memory_path.exists():
            return ""
        content = self._memory_path.read_bytes()
        return hashlib.md5(content).hexdigest()

    def _maybe_rebuild(self) -> None:
        """Rebuild index if MEMORY.md has changed."""
        current_hash = self._get_file_hash()
        stored_hash = self._get_stored_hash()
        if current_hash and current_hash != stored_hash:
            self.rebuild_index()

Read the two branches together. Editing the file produces a different non-empty hash, so the index is rebuilt. Deleting the file produces an empty hash, so the rebuild never runs — and the previous index stays exactly where it was.

That single conditional is the difference between "the user deleted their memory" and "the user deleted the file we read memory from".

What the code says

The same question applies to spending. A memory system that queries on every turn pays for retrieval it already did. One companion app keeps a session snapshot with a TTL, a turn budget and a capacity cap:

export const DEFAULT_RECALL_TTL_MS = 15 * 60 * 1000;
export const DEFAULT_RECALL_MAX_TURNS = 10;
export const SNAPSHOT_MAX_MEMORIES = 40;

const RECALL_TRIGGER_PATTERN = /(记得|还记得|记不记得|上次|上回|之前|以前|曾经|我说过|跟你说过|那天|当时|早先)/;

Four constants decide how much of the conversation the model remembers for free. The trigger regex is written against Chinese phrases — 你还记得 (do you remember), 上次 (last time), 之前 (before) — because that is the language the product ships in. The lesson is not the language: when the user explicitly points at the past, the snapshot is bypassed and a real recall runs. Caching recall silently is how an assistant ends up saying "I don't have that" about something it was told an hour ago.

Deleting is a verification problem, not a delete call

The interesting part of deletion is not the call, it is the report. Delete functions usually count successes as "the gateway returned". That number is a claim about your code, not about the database.

The version I trust counts the state after deletion. It re-lists the source of the memory and reports how many rows are still visible:

  if (input.gateway.listBySourceConversation) {
    try {
      const stillThere = await input.gateway.listBySourceConversation({
        visitorId: input.visitorId,
        companionId: input.companionId,
        conversationId: input.conversationId,
        appId: input.appId,
      });
      result.remaining = stillThere.length;
    } catch (error) {
      result.failed += 1;
    }
  }

A delete that returned successfully but left the row behind counts as nothing. Because the whole operation is summed as scanned = skipped + deleted + failed, the arithmetic itself catches a candidate that was neither deleted nor reported as failed.

There is one more field worth copying: whether the candidate list was exhaustive. A search-based lister is truncated at some limit, and past that limit "not found" and "does not exist" are indistinguishable. If the backend cannot list by source, the report says partial instead of cleared.

When you should not have memory at all

Memory is a liability with a feature attached: it is personal data you now store, expire and delete on request. Three cases where the honest answer is no memory.

The task is stateless. A formatter, a converter, a reviewer that takes a diff and returns comments: none of them benefit from remembering last week.
You cannot name the deletion procedure. If the answer to "delete this user's memory" is "run the delete endpoint and hope", you have a compliance problem rather than a feature.
The memory would only restate the recent conversation. Long-term memory earns its cost on cross-session, cross-time facts. Inside one session the transcript already has them.

The reverse view

The opposite design is defensible too: make memory explicit and user-visible, a file the person can open and edit, with the index treated as a cache that may be rebuilt at any time. That trades recall quality for inspectability, and for a personal tool it is often the better trade — the user can see what the agent knows and correct it in a text editor.

What does not work is the middle: an opaque store with a visible file in front of it, where the two can disagree and nobody can tell which one answered the question.

Both questions — where it lives, and what survives a delete — have to be answerable in one sentence each. If they are not, the memory design is not finished.

The full implementations are in the open-source repositories: Deep-Whisper for the snapshot and the deletion path, and Company-Brain for the knowledge-base side. The longer version of this article, with a file and line number on every claim, is at aiengstore.com/blog/agent-memory. More of these systems are at aiengstore.com.

Human-in-the-loop approval: where the gate actually lives

William Shi — Sun, 08 Nov 2026 11:04:38 +0000

An agent that runs unattended will eventually reach a step that cannot be undone. A post goes out, a message is sent, a record is deleted. Human-in-the-loop approval is not a UI feature bolted on top — it is a decision about where a person stands relative to that step.

There are three common placements. They differ in what a mistake costs and what every run costs.

Three placements

1. Act first, review the log. The agent executes everything and appends each step to an event log. A person reads it afterwards. Nothing blocks, so the run stays cheap. Fine for reversible actions — a draft, a branch, a staging change. It fails on irreversible ones, because a published post turns the review into a record rather than a decision.

2. Approve before the step runs. The run stops and waits. Nothing happens until a decision arrives. This costs latency and someone on call. If every step waits, the agent becomes a form and people start approving without reading.

3. Approve in a separate queue. Risky steps are lifted out of the run into a queue a person works through. Scales better than blocking one run at a time, but costs a second state machine: the queue and the run have to agree on what is pending, and a resumed run may act on a world that moved while it waited.

I built the second one, and the interesting part is not the approve button — it is what parks the run.

The gate is five pieces

A flag on the plan, the rule that sets it, the promise that parks the run, the decision that resolves it, and the event log that records both.

The plan is data. Every task carries a lane, a day range and an approval flag, so the gate is decided when the plan is made rather than improvised while it runs:

lane: "research" | "draft" | "publish" | "reply" | "report";
reason: string;                      // why this task exists, in the model's words
estimated_days: [number, number];    // [start day, end day], e.g. [1, 3]
requires_approval: boolean;

The rule is in the normaliser, not the prompt. Anything in the publish lane requires approval, whatever the model returned:

tasks: parsed.tasks.map((t, i) => ({
  ...t,
  id: t.id || `t-${i + 1}`,
  requires_approval: t.lane === "publish" || t.requires_approval === true,
})),

This is the difference between a policy and a suggestion. A prompt that says "please be careful" is not a gate.

The wait is a promise, not a poll. Nothing spins, no worker is held:

waitForApproval: () =>
  new Promise<ApprovalDecision>((resolve) => {
    rec.pendingApproval = resolve;
  }),

A decision resolves that promise. Returning false when nothing was waiting is what makes a double-approve a no-op instead of a race:

function decide(id: string, decision: ApprovalDecision): boolean {
  const rec = goals.get(id);
  const resolve = rec?.pendingApproval;
  if (!rec || !resolve) return false;
  rec.pendingApproval = null;
  rec.summary.status = "running";
  resolve(decision);
  return true;
}

Where this build stops being a reference

The pause lands on a scripted day — the runner checks day === 12 and raises the request against a fixed task. The flag is real and travels with the plan, but the timeline that plays it is compressed and scripted. It is not a scheduler that scans every task for a flag.

The promise lives inside the process. The store is an in-memory map, so an approval pending across a restart is lost rather than recovered. That is a boundary of the demo, not a property to build on.

Two things I would keep: the decision is an HTTP call that returns 409 when the run is not waiting, and every event — approvals included — is appended with a sequence number. That is what makes the run replayable afterwards, which matters more than the approval itself. An approval you cannot audit is just a click.

The other direction: remove the capability

Blocking the run is one answer. The other is removing the capability entirely: the agent may read the queue and recommend, but the tool that approves is not in its toolset.

The approving tool sits in a separate high-risk list the surrounding code uses, and the agent's allowed set simply does not contain it. The capability is removed rather than discouraged.

That is a stronger guarantee than any instruction in a system prompt, and it is cheaper — no state machine, no pending promises. It only works when the decision is easy to separate from the judgement. For "should this fact be approved", it does.

Where this comes from

Both systems I quoted are open source, so you can read the rest yourself:

DeepSeek Harness Desktop — the desktop agent runtime. Session-level permission presets (Read Only / Workspace Write / Full access) rather than a prompt asking the model to be careful, crash recovery around the loop, and the function-call wiring.
Company Brain — the knowledge-graph RAG stack the review tool comes from. Entities and relations in PostgreSQL + Apache AGE, three retrieval engines in one workspace, cited answers.

They are part of a larger collection at aiengstore.com — full source for the systems most teams end up rebuilding. Alongside the open-source ones it covers:

Agents and orchestration — goal-driven runners that plan, pause for human approval and replay every decision; multi-agent routing where the hard part is deciding which agent owns a task boundary, not making them talk; long-running operations agents with event-sourced logs.

Retrieval and knowledge — hybrid retrieval that fuses dense and lexical ranking (and why BM25 tokenisation quietly breaks on product codes and non-Latin text); GraphRAG that survives a real corpus instead of a demo one; agent memory that addresses the two questions tutorials skip — when does it get rebuilt, and what actually remains after a delete.

Documents and extraction — review that returns page coordinates rather than a summary, so a finding can be located; NL-to-SQL with the schema reasoning kept visible; document pipelines that handle scanned PDFs.

Analytics and internal tools — operational dashboards over agent runs, knowledge bases that stay queryable as they grow.

The written guides go deeper than this post in exactly one way: every claim carries a file and line number you can open. If you want the version of this article with all the citations, it is at aiengstore.com/blog/human-approval.