agent-memory-layer

name	agent-memory-layer
description	Scalable memory system for AI agents with short-term, long-term, and episodic memory. Use when building agent memory persistence, conversation context management, knowledge retrieval, or episodic recall. Covers Redis-backed short-term memory, vector-based long-term memory, and timeline-ordered episodic memory with decay and consolidation.

Agent Memory Layer

Three-tier memory system for AI agents: short-term, long-term, and episodic.

Quick Start

from memory_layer import AgentMemory

mem = AgentMemory(agent_id="my-agent")
mem.short_term.add("User prefers dark mode", priority=0.8)
mem.long_term.store("Project uses React + TypeScript", tags=["tech", "project"])
mem.episodic.record("Debugged auth bug", outcome="success", duration_min=15)

# Recall
context = mem.short_term.recall(limit=10)
relevant = mem.long_term.search("frontend framework")
similar = mem.episodic.find_similar("debugging session")

Architecture

┌─────────────────────────────────────────┐
│            Agent Memory                  │
├───────────┬───────────┬─────────────────┤
│ Short-Term│ Long-Term │   Episodic      │
│ (Redis)   │ (Vectors) │  (Timeline)     │
│ TTL: 1hr  │ Permanent │ Decay: 30d      │
│ Hot cache │ Semantic  │ Consolidated    │
└───────────┴───────────┴─────────────────┘

Memory Tiers

Short-Term (Working Memory)

• Recent context, active conversation, current task state
• TTL-based expiry (default 1 hour)
• Priority-weighted retention
• See references/short-term.md

Long-Term (Knowledge)

• Persistent facts, preferences, learned patterns
• Vector similarity search for retrieval
• Tags and metadata for filtering
• See references/long-term.md

Episodic (Experience)

• Timeline-ordered events with outcomes
• Decay function reduces old episode weight
• Consolidation moves recurring patterns to long-term
• See references/episodic.md

Consolidation

Episodic memories that recur are automatically promoted to long-term:

• If the same outcome occurs 3+ times → store as learned pattern
• Failed approaches get negative weight in long-term
• See scripts/consolidate.py