<!-- Canonical: https://lucioduran.com/projects/agent-memory-lifecycle
Language: en
Content-SHA256: 6e4c452dbc4aaa1e352223bdf6d2c2ca14611e4ea0d08156848857110245b294
-->

[Projects](<https://lucioduran.com/projects>) / Agent Memory Lifecycle

# Agent Memory Lifecycle

Auditable memory events with provenance, corrections, expiry, deletion and session-scoped lexical retrieval.

Author: [Lucio Durán](<https://lucioduran.com/>) · Python 3.11.13 · License: [MIT](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/LICENSE>)

Page published: 2026-11-09 · Page updated: 2026-11-09

[Repository](<https://github.com/lucioduran/agent-memory-lifecycle>) · [Original evidence](<https://raw.githubusercontent.com/lucioduran/agent-memory-lifecycle/d185070cadfd4d0b36e58d957ab7054ae90bdf18/results/evaluation.json>) · [Release v0.1.0](<https://github.com/lucioduran/agent-memory-lifecycle/releases/tag/v0.1.0>)

## Problem and relevance to agents

Append-only memory may retrieve an obsolete fact after it has expired, been corrected or been deleted. Retrieval scores alone do not explain whether a fact should remain usable.

Explicit lifecycle decisions make memory selection inspectable before an agent consumes the selected facts.

## Architecture

1. **Validate events.** Assertions, corrections and tombstones carry source, session, recording time and validity bounds.
2. **Resolve before ranking.** Filter session and validity, apply permanent corrections and deletions, and select one winning value per key before TF-IDF cosine retrieval.
3. **Explain and replay.** Return conflicts, exclusions and provenance. Sanitized exports preserve replay structure while removing deleted payloads.

- [Design and trust boundaries](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/docs/semantics.md>)

## What this demonstrates

- Deterministic correction and expiration semantics, including boundary timestamps.
- Cross-session selection and deletion checks with explicit expected IDs.
- Replayable traces showing why memory was selected or excluded.

## Published results

Eighteen original fictional policy scenarios executed locally on a Xeon W-3223 using Python 3.11.13 and one thread.

Exact top-one ID set matches include empty expected results. Both methods filter by session. The baseline ignores corrections, expiry and deletion and uses simpler lexical ranking.

### Lifecycle policy cases

| Method | Exact expected ID sets |
| --- | --- |
| Session-scoped append-only baseline | 8/18 |
| Temporal policy and TF-IDF | 18/18 |

All policy scenarios passed, but the baseline comparison changes both ranking and lifecycle rules. It does not isolate a causal retrieval-quality gain. A single elapsed time is not a latency benchmark.

## Reproduce

Python 3.11 or newer; replay and evaluation have no runtime dependencies.

Run measurements in a new destination and serialize heavy workloads. Within the original project series, use the shared benchmark\_lock.py wrapper. Commands below use POSIX shell syntax.

### Verify saved evidence

```
git clone https://github.com/lucioduran/agent-memory-lifecycle.git
cd agent-memory-lifecycle
git checkout d185070cadfd4d0b36e58d957ab7054ae90bdf18
python -m scripts.evaluate results/evaluation.json --verify
```

### Repeat the local experiment

```
python -m scripts.evaluate results/new-run.json
```

## Scope and limitations

- The in-memory library assumes trusted callers and files. It provides no authentication, concurrency control, crash durability, encryption or secure erasure.
- Deletion retains audit identifiers and timestamps and cannot erase external copies or old traces. Erased correction keys cannot be revalidated from sanitized exports.
- Newer facts win by policy, not because they have been verified as true. Historical queries use current knowledge.
- ASCII lexical retrieval and small author-known fixtures do not establish semantic understanding, production accuracy or security.

- [Related architecture article](<https://lucioduran.com/blog/agentic-ai-architecture-patterns>)

## Sources and revision

The report identifies implementation commit 7b9a6b77399c38e461544c7897f812bab6e96ebd and a fixture hash, but contains no execution timestamp. The release and page dates are separate.

- Reviewed revision: [` d185070cadfd4d0b36e58d957ab7054ae90bdf18 `](<https://github.com/lucioduran/agent-memory-lifecycle/commit/d185070cadfd4d0b36e58d957ab7054ae90bdf18>)
- Revision recorded by the experiment: [` 7b9a6b77399c38e461544c7897f812bab6e96ebd `](<https://github.com/lucioduran/agent-memory-lifecycle/commit/7b9a6b77399c38e461544c7897f812bab6e96ebd>)
- Release published: [v0.1.0](<https://github.com/lucioduran/agent-memory-lifecycle/releases/tag/v0.1.0>) · 2026-11-09T18:31:34Z
- Corpus SHA-256: ` 05a8e826369607eb05d5bcf9f67783db6161ed565e35d05f0313a983c37459dc `

- [README and usage](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/README.md>)
- [Original evidence](<https://raw.githubusercontent.com/lucioduran/agent-memory-lifecycle/d185070cadfd4d0b36e58d957ab7054ae90bdf18/results/evaluation.json>)
- [MIT license](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/LICENSE>)
- [Design and trust boundaries](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/docs/semantics.md>)
- [Measurement methodology](<https://github.com/lucioduran/agent-memory-lifecycle/blob/d185070cadfd4d0b36e58d957ab7054ae90bdf18/docs/evaluation.md>)
- [Original fixtures](<https://raw.githubusercontent.com/lucioduran/agent-memory-lifecycle/d185070cadfd4d0b36e58d957ab7054ae90bdf18/examples/scenarios.json>)