For students learning AI engineering

Memory that expires, and a deletion you can prove

Saving memories is the easy half. The hard half is deciding when a memory is stale, and what it means to delete one.

DeepWhisper answers the first with a session snapshot instead of a query per turn: the snapshot stays trusted for fifteen minutes or ten turns, holds at most forty entries, and any phrase like "do you remember" forces a real recall instead of reusing the cache.

It answers the second with a verification step that most projects skip. After deleting, it lists the source conversation again and reports how many rows are still visible. A delete call that returned successfully but left the row behind counts as nothing, and the report says so in a field rather than in an apology.

Read the companion file too. The forget path lives next to a store and a job module, and the split is the lesson: pure decision logic in one file, database access in another, so the rules can be tested without a provider.

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

/**
 * Snapshot capacity cap.
 *
 * The snapshot is the working set of the last recall (30 entries by default) and
 * the write path adds to and edits it in place, so it has to be capped.
 */
export const SNAPSHOT_MAX_MEMORIES = 40;

const RECALL_TRIGGER_PATTERN = /(记得|还记得|上次|之前|我说过)/;

  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;

An approval gate that is a setting, not a sentence in the prompt

The desktop runtime gates work with a permission preset attached to the session: read only, workspace write, full access. The catalog of presets is deliberately process-level and separate from session history, and the current selection is its own small projection.

Two details are worth stealing. The host confirms every change through the session projection, so the interface cannot silently widen a permission and call it a UI state. And a value the user assembled from several presets is display state only, never a selectable target: you cannot accidentally re-apply a permission that was never a named preset.

The alternative design, asking the model in the system prompt to be careful, has no enforcement point. This one does.

The catalog is also a small study in staleness. Two invalidation sources feed one reader, and the reader publishes an empty state before each replacement read, so a surface that must drop its options never shows a catalog from the previous host generation.

/**
 * Process-level permission catalog. It changes with live contributions and is
 * deliberately separate from Session history.
 */
export interface PermissionCatalog {
  options: PresetOption[]
  defaultOptions: PresetOption[]
  defaultPreset: string
}

/** Whole `permissions` Session projection: current durable selection only. */
export interface PermissionSelection {
  currentValue: string
}

Hybrid retrieval with the fusion left visible

CompanyBrain runs three retrieval engines, and one of them is a plain hybrid searcher you can read end to end. Vectors and keyword results are collected separately, each candidate keeps the rank it had in each list, and the two are fused with reciprocal rank fusion.

Because the score is written as a formula rather than hidden in a library call, you can see the two decisions it makes: the constant K controls how quickly a first-place hit stops dominating, and the ordering breaks ties by the raw score of the best list. The final threshold is applied to an RRF score normalised against the best candidate of this query, not against a fixed number.

def rrf_score(candidate: SearchCandidate) -> float:
    return sum(1.0 / (RRF_K + rank) for rank in candidate.ranks.values())

    ordered = sorted(candidates.values(), key=lambda candidate: (rrf_score(candidate), max(candidate.raw_scores.values() or [0])), reverse=True)

What you get that a tutorial cannot give you

These repositories carry the parts a course leaves out: evaluation harnesses with stored reports, migration scripts, and comments that record bugs the authors found in their own code.

The gateway is a good example. A high-risk tool is simply not exposed to the agent, and the comment above it says the tool stays out until a confirmation token exists. That is what production discipline looks like at the smallest scale: the capability is removed, not discouraged.

const HIGH_RISK_NANO_TOOLS = new Set([
  // Not exposed by default before M30; must gain a confirmation token first.
  'nano_admin_review_fact_submission',
]);

A reading order that works

Do not start at the repository root. Pick one behaviour you can observe in the running product, then follow it down until it stops being interesting.

For memory, start at the snapshot constants and walk outwards to the store, then to the forget path. For approvals, start at the preset types and follow the selection into the session projection. For retrieval, start at the fusion function, then read the SQL that produced the two ranked lists it is fusing.

Keep a scratch file of the questions each layer answers. When a layer stops answering a new question, you have reached the boundary of that subsystem and can move sideways instead of downwards.