agent-memory

name	agent-memory
description	Add persistent memory to AI coding agents — file-based, vector, and semantic search memory systems that survive between sessions. Use when a user asks to "remember this", "add memory to my agent", "persist context between sessions", "build a knowledge base for my agent", "set up agent memory", or "make my AI remember things". Covers file-based memory (MEMORY.md), SQLite with embeddings, vector databases (ChromaDB, Pinecone), semantic search, memory consolidation, and automatic context injection.
license	Apache-2.0
compatibility	Node.js 18+ or Python 3.10+. Optional: ChromaDB, Pinecone, OpenAI API for embeddings.
metadata	{"author":"terminal-skills","version":"1.0.0","category":"data-ai","tags":["memory","persistence","embeddings","vector-search","context","rag"]}

Agent Memory

Overview

AI agents forget everything between sessions. This skill builds persistent memory systems — from simple file-based approaches to full vector-search architectures — so agents retain context, learn from past interactions, and make better decisions over time.

When to Use

• User wants the agent to remember decisions, preferences, or project context
• Building a coding assistant that needs to recall past conversations
• Creating a knowledge base the agent can query semantically
• Agent needs to learn from mistakes and not repeat them
• Implementing memory consolidation (daily notes → long-term memory)

Instructions

Strategy 1: File-Based Memory (Zero Dependencies)

The simplest approach — write memories to structured markdown files. No database, no embeddings, no API keys. Works with any agent that can read/write files.

Architecture

memory/
├── MEMORY.md              # Long-term curated knowledge
├── 2026-02-24.md          # Daily session logs
├── 2026-02-23.md
├── entities/
│   ├── projects.md        # Known projects and their state
│   ├── people.md          # People, preferences, relationships
│   └── decisions.md       # Key decisions and reasoning
└── heartbeat-state.json   # Periodic check state

Memory File Format

# MEMORY.md — Long-Term Agent Memory

## Projects
### Terminal Skills
- Repo: https://github.com/TerminalSkills/skills
- Stack: Next.js, TypeScript
- Status: Active, 295 skills published
- Key decision: Use-cases always come first, skills serve use-cases

## Preferences
- Language: TypeScript over JavaScript
- Testing: Vitest over Jest
- Deployment: Vercel for frontend, Railway for backend

## Lessons Learned
- Sub-agents limited to 5-6 tasks max (context window overflow at 10+)
- Always check for duplicates before creating new content
- Git branches from upstream/main, never local main

Implementation

# agent_memory.py — File-based agent memory with search
"""
File-based memory system for AI agents.
Stores memories as structured markdown, supports fuzzy search
across all memory files without any external dependencies.
"""
import os
import re
from datetime import datetime, timedelta
from pathlib import Path
from typing import Optional

class FileMemory:
    """Persistent file-based memory for AI agents."""

    def __init__(self, memory_dir: str = "memory"):
        self.memory_dir = Path(memory_dir)
        self.memory_dir.mkdir(parents=True, exist_ok=True)
        self.long_term_file = self.memory_dir / "MEMORY.md"
        self.entities_dir = self.memory_dir / "entities"
        self.entities_dir.mkdir(exist_ok=True)

    def log_today(self, content: str, section: str = "Notes") -> str:
        """Append to today's daily log file.

        Args:
            content: The memory content to log
            section: Section header within the daily file

        Returns:
            Path to the updated file
        """
        today = datetime.now().strftime("%Y-%m-%d")
        daily_file = self.memory_dir / 

          daily_file.exists():
            daily_file.write_text()

         (daily_file, )  f:
            f.write()

         (daily_file)

     () -> :
        
        content = .long_term_file.read_text()  .long_term_file.exists()  

        
        section_header = 
         section_header   content:
            content += 

        
        entry = 
        insert_pos = content.index(section_header) + (section_header) + 
        content = content[:insert_pos] + entry + content[insert_pos:]

        .long_term_file.write_text(content)

     () -> []:
        
        terms = query.lower().split()
        results = []

         md_file  .memory_dir.rglob():
            lines = md_file.read_text().splitlines()
             i, line  (lines):
                line_lower = line.lower()
                score = (  term  terms  term  line_lower)
                 score > :
                    results.append({
                        : (md_file.relative_to(.memory_dir)),
                        : i + ,
                        : line.strip(),
                        : score / (terms),  
                    })

        results.sort(key= x: x[], reverse=)
         results[:max_results]

     () -> :
        
        context_parts = []
         i  (days):
            date = (datetime.now() - timedelta(days=i)).strftime()
            daily_file = .memory_dir / 
             daily_file.exists():
                context_parts.append(daily_file.read_text())

         .join(context_parts)

     () -> :
        
        recent = .get_recent_context(days=)
        
        
         

Strategy 2: SQLite + Embeddings (Local Vector Search)

For agents that need semantic search — "find memories similar to X" rather than keyword matching. Uses SQLite for zero-infrastructure persistence and OpenAI embeddings for semantic similarity.

// memory-store.ts — SQLite-backed semantic memory with vector search
/**
 * Semantic memory store using SQLite + OpenAI embeddings.
 * Stores memories with vector embeddings for similarity search.
 * No external database required — everything in a single .db file.
 */
import Database from "better-sqlite3";
import OpenAI from "openai";

interface Memory {
  id: number;
  content: string;
  category: string;
  embedding: number[];
  created_at: string;
  metadata: Record<string, unknown>;
}

interface SearchResult {
  content: string;
  category: string;
  similarity: number;
  created_at: string;
}

export class MemoryStore {
  private db: Database.Database;
  private openai: OpenAI;
  private model = "text-embedding-3-small"; // $0.02/1M tokens

  constructor() {
    . =  (dbPath);
    . =  ();
    .();
  }

   ():  {
    ..();
  }

  
   (: , :  = , : <, > = {}): <> {
     embedding =  .(content);
     embeddingBlob = .( (embedding).);

     result = ..().(content, category, embeddingBlob, .(metadata));

     result.  ;
  }

  
   (: , :  = , ?: ): <[]> {
     queryEmbedding =  .(query);

     rows = ..(
      category
        ? 
        : 
    ).(...(category ? [category] : []))  <{
      : ; : ; : ; : ;
    }>;

    
     scored = rows.( {
       memoryEmbedding = .( (row..));
       similarity = .(queryEmbedding, memoryEmbedding);
       { : row., : row., similarity, : row. };
    });

    scored.( b. - a.);
     scored.(, limit);
  }

    (: ): <[]> {
     response =  ...({
      : .,
      : text,
    });
     response.[].;
  }

   (: [], : []):  {
     dot = , normA = , normB = ;
     ( i = ; i < a.; i++) {
      dot += a[i] * b[i];
      normA += a[i] * a[i];
      normB += b[i] * b[i];
    }
     dot / (.(normA) * .(normB));
  }
}

Strategy 3: ChromaDB Vector Database (Production Scale)

For agents handling thousands of memories or needing advanced filtering. ChromaDB runs locally or as a service, handles embedding and search automatically.

# chroma_memory.py — Production agent memory with ChromaDB
"""
Vector-based agent memory using ChromaDB.
Handles embedding generation, similarity search, and metadata filtering.
Scales to millions of memories with persistent storage.
"""
import chromadb
from chromadb.config import Settings
from datetime import datetime
from typing import Optional

class ChromaMemory:
    """Production-grade agent memory backed by ChromaDB."""

    def __init__(self, persist_dir: str = "./chroma_db", collection_name: str = "agent_memory"):
        self.client = chromadb.PersistentClient(
            path=persist_dir,
            settings=Settings(anonymized_telemetry=False)
        )
        self.collection = self.client.get_or_create_collection(
            name=collection_name,
            metadata={"hnsw:space": "cosine"}  # Cosine similarity for search
        )

    def store(self, content: str, category: str = "general",
              metadata: Optional[dict] = None) -> str:
        """Store a memory with automatic embedding.

        Args:
            content: Text content to remember
            category: Category for filtering (project, preference, lesson, etc.)
            metadata: Additional metadata (source, confidence, etc.)

        Returns:
            Generated memory ID
        """
        memory_id = 
        meta = {
            : category,
            : datetime.now().isoformat(),
            **(metadata  {})
        }

        .collection.add(
            documents=[content],
            metadatas=[meta],
            ids=[memory_id]
        )
         memory_id

     () -> []:
        
        where_filter = {: category}  category  

        results = .collection.query(
            query_texts=[query],
            n_results=n_results,
            where=where_filter,
            include=[, , ]
        )

        memories = []
         doc, meta, dist  (
            results[][],
            results[][],
            results[][]
        ):
            memories.append({
                : doc,
                : meta.get(),
                :  - dist,  
                : meta.get(),
            })

         memories

     () -> :
        
        .collection.delete(ids=[memory_id])

     () -> :
        
         .collection.count()

Examples

Example 1: Add persistent memory to a Claude Code agent

User prompt: "Set up a memory system for my coding agent so it remembers project decisions, coding preferences, and lessons learned between sessions."

The agent will:

• Create a memory/ directory structure with MEMORY.md, daily logs, and entity files
• Implement the FileMemory class with search and consolidation
• Add session start hook that loads recent context (last 3 days + long-term memory)
• Add session end hook that saves key decisions and new information
• Set up periodic consolidation from daily logs into long-term memory

Example 2: Build semantic search over past conversations

User prompt: "I want my agent to search past conversations by meaning, not just keywords. It should find relevant memories even if the exact words don't match."

The agent will:

• Set up SQLite database with embedding storage
• Configure OpenAI text-embedding-3-small for low-cost vector generation
• Build search function with cosine similarity ranking
• Add automatic memory extraction from conversation turns
• Implement relevance threshold to avoid surfacing weak matches

Example 3: Scale agent memory for a production chatbot

User prompt: "Build a memory system that can handle 100K+ memories for our customer support bot. It needs to remember past tickets, solutions, and customer preferences."

The agent will:

• Deploy ChromaDB with persistent storage
• Design memory schema: categories for tickets, solutions, customer prefs, product docs
• Implement metadata filtering for fast category-scoped queries
• Add memory deduplication to prevent storing near-identical entries
• Build memory aging — reduce relevance weight for old memories

Guidelines

• Start with file-based memory — it works everywhere, has zero dependencies, and is human-readable
• Use embeddings when keyword search fails — "deployment issues" should find "CI/CD pipeline broken"
• Consolidate regularly — daily logs accumulate noise; distill into long-term memory weekly
• Category separation matters — searching "preferences" shouldn't return "bug reports"
• Set memory limits — without pruning, memory grows until it overwhelms context windows
• Privacy by default — never store API keys, passwords, or PII in memory files
• Test recall quality — bad embeddings return irrelevant results; validate with real queries
• Embedding cost — text-embedding-3-small is $0.02/1M tokens; budget ~1M tokens/month for active agents
• ChromaDB vs Pinecone — use ChromaDB for local/self-hosted, Pinecone for managed cloud at scale
• Memory injection — prepend relevant memories to agent system prompt, not user messages