i-spent-four-months-building-long-term-memory-into-my-ai-agents-and-here-is-what-actually-worked-and-what-was-overengineered

# Approach 1: Simple Key-Value Memory — the first thing I built
# Storage: Supabase (PostgreSQL)
# Retrieval: exact match or category lookup
# Verdict: works for structured facts, fails for conversational context

import json
from supabase import create_client

supabase = create_client("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY")

def save_memory(user_id: str, category: str, key: str, value: str):
    """Save a structured fact about a user."""
    supabase.table("agent_memory").upsert({
        "user_id": user_id,
        "category": category,  # e.g. 'preference', 'fact', 'history'
        "key": key,            # e.g. 'preferred_contact_time'
        "value": value,        # e.g. 'Tuesday afternoon'
        "updated_at": "now()"
    }).execute()

def get_memory(user_id: str, category: str = None) -> str:
    """Retrieve memories for a user, optionally filtered by category."""
    query = supabase.table("agent_memory").select("*").eq("user_id", user_id)
    if category:
        query = query.eq("category", category)
    result = query.execute()

    if not result.data:
        return ""

    memory_text = "What I know about this user:\n"
    for row in result.data:
        memory_text += f"- {row['key']}: {row['value']}\n"
    return memory_text

def build_prompt_with_memory(user_id: str, user_message: str) -> str:
    """Build an agent prompt that includes retrieved memory."""
    memory = get_memory(user_id)
    system_prompt = f"""You are a helpful assistant.

{memory}

Use this context naturally in your responses. Do not mention that you have
a memory system. Just use the information as a knowledgeable assistant would."""
    return system_prompt

# What this handled well:
# - User preferences ('prefers email over phone')
# - Company facts ('their product is called ProTrack, not ProTracker')
# - Standing instructions ('always suggest the Pro plan first')
#
# What it failed on:
# - Conversational continuity ('last week you said you were unhappy with...')
# - Connecting disparate topics from different sessions
# - Knowing which past facts were still relevant vs outdated
#
# The e-commerce client was happy with this for structured preferences.
# The executive assistant client found it too rigid — it could not
# recall conversational context, only structured facts.

# Approach 2: Vector Semantic Memory — more powerful, more complex
# Storage: Supabase with pgvector extension (or Pinecone)
# Retrieval: semantic similarity search
# Verdict: excellent recall, higher cost, overengineered for simple agents

from openai import OpenAI
from supabase import create_client
import json

client = OpenAI(api_key="YOUR_KEY")
supabase = create_client("YOUR_URL", "YOUR_KEY")

def embed_text(text: str) -> list[float]:
    """Convert text to vector embedding using OpenAI."""
    response = client.embeddings.create(
        model="text-embedding-3-small",  # $0.02 per million tokens
        input=text
    )
    return response.data[0].embedding

def save_memory_vector(user_id: str, content: str, metadata: dict = {}):
    """Save a memory with its vector embedding for semantic retrieval."""
    embedding = embed_text(content)
    supabase.table("vector_memory").insert({
        "user_id": user_id,
        "content": content,
        "embedding": embedding,
        "metadata": json.dumps(metadata),
        "created_at": "now()"
    }).execute()

def retrieve_relevant_memories(user_id: str, query: str, top_k: int = 5) -> str:
    """
    Find the most semantically similar past memories to the current query.
    Requires pgvector extension in Supabase.
    SQL: SELECT content FROM vector_memory
         WHERE user_id = $1
         ORDER BY embedding <=> $2 LIMIT $3
    """
    query_embedding = embed_text(query)

    # pgvector cosine similarity search via Supabase RPC
    result = supabase.rpc("match_memories", {
        "query_embedding": query_embedding,
        "match_user_id": user_id,
        "match_count": top_k
    }).execute()

    if not result.data:
        return ""

    memories = "Relevant context from previous conversations:\n"
    for item in result.data:
        memories += f"- {item['content']}\n"
    return memories

# What this handled well:
# - 'Remember when we discussed the Q3 campaign?' → found semantically
#   similar content even with different phrasing
# - Connecting related topics across sessions
# - High-volume agents where exact-match lookup would miss context
#
# What it failed on:
# - Cost: embedding every utterance added $2-8/month in API costs per agent
# - Latency: embedding + vector search added 200-400ms per request
# - Storage management: memories accumulated without expiry logic
#   and old contradictory information persisted alongside new facts
#
# Used this for the executive assistant agent. Client noticed the
# improvement in contextual recall immediately. Also noticed the
# slightly slower response time.

# The simplest memory approach that satisfied most client needs
# No vector database, no embedding costs, minimal complexity
# Works for agents where structured context matters most

import json
from datetime import datetime

# Single JSON file per user (or Supabase row for production)
def load_user_context(user_id: str) -> dict:
    """Load the user's persistent context object."""
    try:
        with open(f"context_{user_id}.json", "r") as f:
            return json.load(f)
    except FileNotFoundError:
        return {
            "user_id": user_id,
            "facts": [],           # key facts about the user
            "preferences": {},     # structured preferences
            "last_topics": [],     # last 5 topics discussed
            "open_items": [],      # pending items from last session
            "last_session": None
        }

def update_user_context(user_id: str, conversation_summary: str,
                        new_facts: list, ai_client) -> None:
    """
    After each session, use the AI to extract and update context.
    This runs once at session end — not during conversation.
    """
    context = load_user_context(user_id)

    update_prompt = f"""
    Current user context:
    {json.dumps(context, indent=2)}

    This session summary:
    {conversation_summary}

    Update the context object. Rules:
    - Add new facts to 'facts' list (max 20, remove oldest if over)
    - Update preferences if user stated any clearly
    - Set 'last_topics' to the main 3 topics from this session
    - Set 'open_items' to anything the user asked to follow up on
    - Remove resolved items from open_items

    Return ONLY valid JSON matching the context structure. No other text.
    """

    response = ai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": update_prompt}],
        max_tokens=800
    )

    try:
        updated_context = json.loads(response.choices[0].message.content)
        updated_context["last_session"] = datetime.now().isoformat()
        with open(f"context_{user_id}.json", "w") as f:
            json.dump(updated_context, f, indent=2)
    except json.JSONDecodeError:
        pass  # Keep existing context if update fails

def build_prompt_with_context(user_id: str, user_message: str) -> str:
    """Build agent system prompt with user context injected."""
    context = load_user_context(user_id)

    context_summary = ""
    if context["facts"]:
        context_summary += "What I know: " + "; ".join(context["facts"][-10:]) + "\n"
    if context["open_items"]:
        context_summary += "Pending from last session: " + "; ".join(context["open_items"]) + "\n"
    if context["last_topics"]:
        context_summary += "Last talked about: " + ", ".join(context["last_topics"])

    return f"""You are a helpful assistant.\n\n{context_summary}"""

# Cost: ~$0.001 per session end update using GPT-4o-mini
# Latency: zero added to real-time conversation (runs post-session)
# Coverage: 80% of what clients needed from memory
# Missing: semantic recall of specific past statements