Pruning: When Forgetting Is a Feature

Introduction

There is a dangerous myth about memory systems: that more is better. Store everything. Never delete. Build the richest possible record.

In practice, a memory store that never forgets becomes less useful over time, not more. Stale facts surface alongside current ones. Superseded decisions compete with the ones that replaced them. Hypotheses from debugging sessions three years ago pollute queries about current architecture. The store fills with noise until the signal becomes hard to find.

Pruning is the maintenance discipline that keeps a memory store useful. It is not information destruction — done correctly, it is information curation.

Core Concept

Why Stale Memories Are Dangerous

Consider this scenario: two years ago, you stored "use pymongo 3.x — pymongo 4.x has breaking changes in our stack." At the time, this was a useful and accurate warning.

Fourteen months later, your team migrated to pymongo 4.x and updated all the callsites. The work is done. Nobody updated the memory store.

Now an agent queries memory about database libraries. It retrieves the pymongo warning — still stored, still appearing with high confidence because it was carefully entered. The agent avoids pymongo 4.x, which is now the correct and only version in use. The agent's behavior is wrong because its memory is stale.

This is not a corner case. Every piece of stored knowledge has a natural shelf life. Infrastructure decisions change. Libraries update. Teams change their standards. Architecture evolves. A memory store that does not account for time degrades from an asset into a misleading record.

Soft-Delete vs. Hard Delete

The correct primitive for removing a memory entry is soft-delete, not permanent deletion.

Hard delete removes the entry from the store entirely. The information is gone. Reasons this is problematic:

You lose the audit trail: what was believed, when, and why it was changed
If the replacement fact turns out to be wrong, you cannot recover the original
Future agents cannot understand the lineage of a decision — just the current state

Soft-delete marks the entry as superseded and optionally links it to the replacement entry. The entry is no longer returned by default queries, but it remains in the store as an archived record.

In the semantic memory layer, this is implemented via memory_forget, which marks a memory as superseded rather than removing it. The superseded memory's memory_id is preserved. If the operator later discovers the "superseded" fact was actually still correct, recovery is a single operation.

This matches how good organizations handle policy changes: the old policy document is archived and marked "superseded by [new policy, date]," not shredded. The history of decisions is organizational knowledge.

Trust Score Decay as the Early Warning System

Pruning is reactive — you identify and remove stale entries. Trust score decay is proactive — entries automatically signal when they need human review.

A simple decay model, using the −0.1 per 90 days rate:

Entry stored at 0.9 confidence
After 90 days without reconfirmation: drops to 0.8
After 180 days: drops to 0.7
After 12 months: drops to 0.5 — at the review threshold, flagged for human review
After 18 months: drops to 0.3 (flagged as likely stale, query results include a staleness warning)

When an agent retrieves a memory with confidence below 0.5, it should treat it as a lead to verify, not a fact to act on directly. The agent can say: "I have a stored entry about X, but it is 14 months old and may be stale. Can you confirm it is still accurate before I act on it?"

This catches the dangerous case without requiring constant manual review. The decay surface the entries that need attention; humans review and either reconfirm (confidence resets) or supersede (the entry is archived).

What to Prune and When

Clear candidates for pruning:

Version-specific entries where the software version is no longer in use
Process entries for workflows that have been replaced
Debugging hypotheses that were investigated and disproven
Status entries ("project X is blocked") that are now resolved
Configuration entries for systems that have been decommissioned

Not candidates for pruning:

Failure post-mortems — even if the system changed, knowing what went wrong before is valuable pattern knowledge
Architectural decisions with rationale — even deprecated choices explain why the current architecture exists
Trust-score-decayed entries that have not been evaluated — decay signals review, not automatic deletion

Pruning cadence: A quarterly review of entries with confidence below 0.5 is a reasonable starting point. This is a light lift — scanning for flagged entries and either reconfirming, superseding, or archiving each one.

Freshness Metadata

Every memory entry should carry a last_confirmed date separate from the created date. An entry created three years ago that was reconfirmed last week is fresh. An entry created two months ago that has never been reconfirmed may already be stale if the domain changes fast.

last_confirmed is updated when:

A human explicitly reviews and confirms the entry
An agent retrieves the entry, acts on it, and the action succeeds
Automated testing verifies a configuration value still matches the system's actual behavior

Tracking last_confirmed separately from created makes the decay model far more accurate and prevents premature pruning of stable, long-lived facts.

Practical Application

In a production semantic memory layer, every memory entry stored via memory_remember includes metadata: source, date, confidence, and category. The memory_forget tool soft-deletes: the memory is marked superseded, the old confidence drops to 0, and the memory is excluded from future queries — but it remains in the database with its full history.

A concrete example of the pattern in action: when a service's deployment was migrated from Docker to native process supervision, several memory entries about the Docker-based deployment were superseded. The entries were not deleted — they document how the system used to run and why the migration happened. A future agent reading the superseded entries could reconstruct the decision lineage. New entries were stored describing the updated configuration. Queries about the service's deployment now return the current entries; the Docker entries are archived.

This is pruning done correctly: surgical, auditable, and reversible.

Common Mistakes

Pruning based on age alone. A five-year-old decision about the project's primary programming language might be more stable and accurate than a six-month-old guess about a library. Age alone is not a pruning signal — age without reconfirmation is.

Hard-deleting entries to "clean up." Every hard delete destroys provenance. When something goes wrong and you need to understand the history of a decision, you will want the archived record. Default to soft-delete.

Never pruning. The accumulation of stale entries is a slow poison. A store with 10,000 entries, of which 3,000 are stale or superseded, produces noisier query results than a store with 7,000 curated, current entries. Schedule regular reviews.

Pruning too aggressively. An entry about a past failure — even if the failure is fully resolved — is valuable pattern knowledge. Do not prune lessons; prune outdated facts and superseded decisions.

Summary

Stale memories are dangerous — they surface alongside current facts and can mislead agents into following outdated decisions
Soft-delete (mark as superseded) is the correct primitive — hard delete destroys provenance and reversibility
Trust score decay acts as an early warning system, flagging entries that need human review before they cause problems
Prune: version-specific entries for software no longer in use, resolved status entries, disproven hypotheses
Do not prune: failure post-mortems, architectural decisions with rationale, lessons from past incidents
Quarterly review of low-confidence entries is a sustainable maintenance cadence

What's Next

You now have the full toolkit: query-first habit, two kinds of memory, trust scores, one-fact entries, and pruning. In the next lesson, we tie it all together: how to build your own Personal Knowledge OS — a searchable, persistent memory layer that any AI session can draw on. That is the capstone.