Project 4: Memory Store with Provenance

Build a memory system with working, episodic, and semantic layers, each entry carrying provenance, timestamps, and confidence.

Quick Reference

Attribute Value
Difficulty Level 3: Advanced
Time Estimate 12–18 hours
Language Python or JavaScript
Prerequisites Projects 2–3, storage basics
Key Topics memory hierarchy, provenance, retrieval, decay

Learning Objectives

By completing this project, you will:

  1. Implement memory layers (working, episodic, semantic).
  2. Track provenance chains for each memory entry.
  3. Retrieve memories by time, type, and relevance.
  4. Explain decisions by tracing memory lineage.
  5. Design decay policies to avoid memory bloat.

The Core Question You’re Answering

“How can an agent justify its decisions with an auditable memory chain?”

Without provenance, an agent’s memory is just a pile of text. With provenance, it becomes a forensic trail.

Concepts You Must Understand First

Concept Why It Matters Where to Learn
Working vs episodic vs semantic Memory hierarchy design Generative Agents paper
Provenance Traceability of decisions Data lineage references
Retrieval scoring Relevance vs recency IR basics
Decay policies Prevent memory bloat Systems design

Theoretical Foundation

Memory Hierarchy

Working Memory  -> short-term scratchpad
Episodic Memory -> time-stamped events
Semantic Memory -> distilled facts

Provenance Chain

Every decision should be traceable back to:

  • tool outputs
  • observed events
  • user inputs

Project Specification

What You’ll Build

A memory module that stores events, extracts facts, and traces decisions back to sources.

Functional Requirements

  1. Store working, episodic, semantic memory
  2. Track provenance: source, parent_ids, timestamp
  3. Retrieve by time, type, relevance
  4. Trace decisions end-to-end
  5. Apply decay and compaction policies

Non-Functional Requirements

  • Explainable outputs
  • Deterministic retrieval for testing
  • Safe handling of missing parents

Real World Outcome

Example trace output:

Decision: "Compare project.md with backup.md"
  └─ memory_ep_003: "Decided to compare based on user goal"
      └─ memory_ep_001: "User requested file analysis"
          └─ tool_output: {"files_found": ["project.md", "backup.md"]}

Architecture Overview

┌───────────────┐   store   ┌───────────────┐
│ Agent State   │──────────▶│ Memory Store  │
└──────┬────────┘           └──────┬────────┘
       ▼                           ▼
┌───────────────┐          ┌───────────────┐
│ Retriever     │◀────────▶│ Provenance    │
└───────────────┘          └───────────────┘

Implementation Guide

Phase 1: Memory Schema (4–5h)

  • Define memory entry schema
  • Checkpoint: entries stored + loaded

Phase 2: Retrieval + Decay (4–6h)

  • Implement relevance scoring
  • Add decay policies
  • Checkpoint: old memories rank lower

Phase 3: Provenance Tracing (4–7h)

  • Implement trace function
  • Checkpoint: decision shows full chain

Common Pitfalls & Debugging

Pitfall Symptom Fix
Broken chains trace crashes use tombstones for deleted memory
Stale facts wrong decisions add invalidation rules
Memory bloat slow retrieval decay and compaction

Interview Questions They’ll Ask

  1. What’s the difference between episodic and semantic memory?
  2. How do you prevent stale memories from misleading decisions?
  3. Why is provenance critical for debugging agents?

Hints in Layers

  • Hint 1: Start with a JSONL memory log.
  • Hint 2: Add parent_ids for provenance chains.
  • Hint 3: Implement retrieval by recency + relevance.
  • Hint 4: Add compaction to control size.

Learning Milestones

  1. Memory Works: entries stored and retrieved.
  2. Explainable: provenance traces are complete.
  3. Scalable: decay policies keep system fast.

Submission / Completion Criteria

Minimum Completion

  • Working + episodic memory

Full Completion

  • Semantic memory + provenance tracing

Excellence

  • Hybrid retrieval + compaction

This guide was generated from project_based_ideas/AI_AGENTS_LLM_RAG/AI_AGENTS_PROJECTS.md.