20# Agent Memory
21
22## Overview
23
24AI 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.
25
26## When to Use
27
28- User wants the agent to remember decisions, preferences, or project context
29- Building a coding assistant that needs to recall past conversations
30- Creating a knowledge base the agent can query semantically
31- Agent needs to learn from mistakes and not repeat them
32- Implementing memory consolidation (daily notes → long-term memory)
33
34## Instructions
35
36### Strategy 1: File-Based Memory (Zero Dependencies)
37
38The simplest approach — write memories to structured markdown files. No database, no embeddings, no API keys. Works with any agent that can read/write files.
39
40#### Architecture
41
42```
43memory/
44├── MEMORY.md # Long-term curated knowledge
45├── 2026-02-24.md # Daily session logs
46├── 2026-02-23.md
47├── entities/
48│ ├── projects.md # Known projects and their state
49│ ├── people.md # People, preferences, relationships
50│ └── decisions.md # Key decisions and reasoning
51└── heartbeat-state.json # Periodic check state
52```
53
54#### Memory File Format
55
56```markdown
57# MEMORY.md — Long-Term Agent Memory
58
59## Projects
60### Terminal Skills
61- Repo: https://github.com/TerminalSkills/skills
62- Stack: Next.js, TypeScript
63- Status: Active, 295 skills published
64- Key decision: Use-cases always come first, skills serve use-cases
65
66## Preferences
67- Language: TypeScript over JavaScript
68- Testing: Vitest over Jest
69- Deployment: Vercel for frontend, Railway for backend
70
71## Lessons Learned
72- Sub-agents limited to 5-6 tasks max (context window overflow at 10+)
73- Always check for duplicates before creating new content
74- Git branches from upstream/main, never local main
75```
76
77#### Implementation
78
79```python
80# agent_memory.py — File-based agent memory with search
81"""
82File-based memory system for AI agents.
83Stores memories as structured markdown, supports fuzzy search
84across all memory files without any external dependencies.
85"""
86import os
87import re
88from datetime import datetime, timedelta
89from pathlib import Path
90from typing import Optional
91
92class FileMemory:
93 """Persistent file-based memory for AI agents."""
94
95 def __init__(self, memory_dir: str = "memory"):
96 self.memory_dir = Path(memory_dir)
97 self.memory_dir.mkdir(parents=True, exist_ok=True)
98 self.long_term_file = self.memory_dir / "MEMORY.md"
99 self.entities_dir = self.memory_dir / "entities"
100 self.entities_dir.mkdir(exist_ok=True)
101
102 def log_today(self, content: str, section: str = "Notes") -> str:
103 """Append to today's daily log file.
104
105 Args:
106 content: The memory content to log
107 section: Section header within the daily file
108
109 Returns:
110 Path to the updated file
111 """
112 today = datetime.now().strftime("%Y-%m-%d")
113 daily_file = self.memory_dir / f"{today}.md"
114
115 if not daily_file.exists():
116 daily_file.write_text(f"# {today}\n\n")
117
118 with open(daily_file, "a") as f:
119 f.write(f"\n## {section}\n{content}\n")
120
121 return str(daily_file)
122
123 def remember(self, key: str, value: str, category: str = "General") -> None:
124 """Store a key-value memory in long-term storage.
125
126 Args:
127 key: Short identifier for the memory
128 value: The content to remember
129 category: Section to file it under (Projects, Preferences, etc.)
130 """
131 content = self.long_term_file.read_text() if self.long_term_file.exists() else "# Long-Term Memory\n"
132
133 # Find or create category section
134 section_header = f"## {category}"
135 if section_header not in content:
136 content += f"\n{section_header}\n"
137
138 # Append the memory entry
139 entry = f"- **{key}**: {value}\n"
140 insert_pos = content.index(section_header) + len(section_header) + 1
141 content = content[:insert_pos] + entry + content[insert_pos:]
142
143 self.long_term_file.write_text(content)
144
145 def search(self, query: str, max_results: int = 10) -> list[dict]:
146 """Search all memory files for relevant content.
147
148 Args:
149 query: Search terms (supports multiple words)
150 max_results: Maximum number of matching lines to return
151
152 Returns:
153 List of dicts with 'file', 'line_number', 'content', 'score'
154 """
155 terms = query.lower().split()
156 results = []
157
158 for md_file in self.memory_dir.rglob("*.md"):
159 lines = md_file.read_text().splitlines()
160 for i, line in enumerate(lines):
161 line_lower = line.lower()
162 score = sum(1 for term in terms if term in line_lower)
163 if score > 0:
164 results.append({
165 "file": str(md_file.relative_to(self.memory_dir)),
166 "line_number": i + 1,
167 "content": line.strip(),
168 "score": score / len(terms), # Normalize 0-1
169 })
170
171 results.sort(key=lambda x: x["score"], reverse=True)
172 return results[:max_results]
173
174 def get_recent_context(self, days: int = 3) -> str:
175 """Load recent daily logs for context injection.
176
177 Args:
178 days: Number of recent days to include
179
180 Returns:
181 Combined content from recent daily files
182 """
183 context_parts = []
184 for i in range(days):
185 date = (datetime.now() - timedelta(days=i)).strftime("%Y-%m-%d")
186 daily_file = self.memory_dir / f"{date}.md"
187 if daily_file.exists():
188 context_parts.append(daily_file.read_text())
189
190 return "\n---\n".join(context_parts)
191
192 def consolidate(self) -> str:
193 """Review recent daily logs and extract key learnings into long-term memory.
194
195 Returns:
196 Summary of what was consolidated
197 """
198 recent = self.get_recent_context(days=7)
199 # In practice, you'd send this to an LLM to extract key points
200 # Here we return the raw content for manual review
201 return f"Review these notes and update MEMORY.md:\n\n{recent}"
202```
203
204### Strategy 2: SQLite + Embeddings (Local Vector Search)
205
206For 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.
207
208```typescript
209// memory-store.ts — SQLite-backed semantic memory with vector search
210/**
211 * Semantic memory store using SQLite + OpenAI embeddings.
212 * Stores memories with vector embeddings for similarity search.
213 * No external database required — everything in a single .db file.
214 */
215import Database from "better-sqlite3";
216import OpenAI from "openai";
217
218interface Memory {
219 id: number;
220 content: string;
221 category: string;
222 embedding: number[];
223 created_at: string;
224 metadata: Record<string, unknown>;
225}
226
227interface SearchResult {
228 content: string;
229 category: string;
230 similarity: number;
231 created_at: string;
232}
233
234export class MemoryStore {
235 private db: Database.Database;
236 private openai: OpenAI;
237 private model = "text-embedding-3-small"; // $0.02/1M tokens
238
239 constructor(dbPath: string = "agent-memory.db") {
240 this.db = new Database(dbPath);
241 this.openai = new OpenAI();
242 this.initSchema();
243 }
244
245 private initSchema(): void {
246 this.db.exec(`
247 CREATE TABLE IF NOT EXISTS memories (
248 id INTEGER PRIMARY KEY AUTOINCREMENT,
249 content TEXT NOT NULL,
250 category TEXT DEFAULT 'general',
251 embedding BLOB, -- Serialized float32 array
252 metadata TEXT DEFAULT '{}', -- JSON metadata
253 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
254 updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
255 );
256 CREATE INDEX IF NOT EXISTS idx_category ON memories(category);
257 CREATE INDEX IF NOT EXISTS idx_created ON memories(created_at);
258 `);
259 }
260
261 /**
262 * Store a memory with its embedding vector.
263 */
264 async store(content: string, category: string = "general", metadata: Record<string, unknown> = {}): Promise<number> {
265 const embedding = await this.embed(content);
266 const embeddingBlob = Buffer.from(new Float32Array(embedding).buffer);
267
268 const result = this.db.prepare(`
269 INSERT INTO memories (content, category, embedding, metadata)
270 VALUES (?, ?, ?, ?)
271 `).run(content, category, embeddingBlob, JSON.stringify(metadata));
272
273 return result.lastInsertRowid as number;
274 }
275
276 /**
277 * Semantic search — find memories most similar to the query.
278 * Uses cosine similarity between embedding vectors.
279 */
280 async search(query: string, limit: number = 5, category?: string): Promise<SearchResult[]> {
281 const queryEmbedding = await this.embed(query);
282
283 let rows = this.db.prepare(
284 category
285 ? SELECT content, category, embedding, created_at FROM memories WHERE category = ? ORDER BY created_at DESC LIMIT 1000
286 : SELECT content, category, embedding, created_at FROM memories ORDER BY created_at DESC LIMIT 1000
287 ).all(...(category ? [category] : [])) as Array<{
288 content: string; category: string; embedding: Buffer; created_at: string;
289 }>;
290
291 // Calculate cosine similarity for each memory
292 const scored = rows.map((row) => {
293 const memoryEmbedding = Array.from(new Float32Array(row.embedding.buffer));
294 const similarity = this.cosineSimilarity(queryEmbedding, memoryEmbedding);
295 return { content: row.content, category: row.category, similarity, created_at: row.created_at };
296 });
297
298 scored.sort((a, b) => b.similarity - a.similarity);
299 return scored.slice(0, limit);
300 }
301
302 private async embed(text: string): Promise<number[]> {
303 const response = await this.openai.embeddings.create({
304 model: this.model,
305 input: text,
306 });
307 return response.data[0].embedding;
308 }
309
310 private cosineSimilarity(a: number[], b: number[]): number {
311 let dot = 0, normA = 0, normB = 0;
312 for (let i = 0; i < a.length; i++) {
313 dot += a[i] * b[i];
314 normA += a[i] * a[i];
315 normB += b[i] * b[i];
316 }
317 return dot / (Math.sqrt(normA) * Math.sqrt(normB));
318 }
319}
320```
321
322### Strategy 3: ChromaDB Vector Database (Production Scale)
323
324For agents handling thousands of memories or needing advanced filtering. ChromaDB runs locally or as a service, handles embedding and search automatically.
325
326```python
327# chroma_memory.py — Production agent memory with ChromaDB
328"""
329Vector-based agent memory using ChromaDB.
330Handles embedding generation, similarity search, and metadata filtering.
331Scales to millions of memories with persistent storage.
332"""
333import chromadb
334from chromadb.config import Settings
335from datetime import datetime
336from typing import Optional
337
338class ChromaMemory:
339 """Production-grade agent memory backed by ChromaDB."""
340
341 def __init__(self, persist_dir: str = "./chroma_db", collection_name: str = "agent_memory"):
342 self.client = chromadb.PersistentClient(
343 path=persist_dir,
344 settings=Settings(anonymized_telemetry=False)
345 )
346 self.collection = self.client.get_or_create_collection(
347 name=collection_name,
348 metadata={"hnsw:space": "cosine"} # Cosine similarity for search
349 )
350
351 def store(self, content: str, category: str = "general",
352 metadata: Optional[dict] = None) -> str:
353 """Store a memory with automatic embedding.
354
355 Args:
356 content: Text content to remember
357 category: Category for filtering (project, preference, lesson, etc.)
358 metadata: Additional metadata (source, confidence, etc.)
359
360 Returns:
361 Generated memory ID
362 """
363 memory_id = f"mem_{datetime.now().strftime('%Y%m%d_%H%M%S_%f')}"
364 meta = {
365 "category": category,
366 "created_at": datetime.now().isoformat(),
367 **(metadata or {})
368 }
369
370 self.collection.add(
371 documents=[content],
372 metadatas=[meta],
373 ids=[memory_id]
374 )
375 return memory_id
376
377 def recall(self, query: str, n_results: int = 5,
378 category: Optional[str] = None) -> list[dict]:
379 """Semantic search for relevant memories.
380
381 Args:
382 query: Natural language query
383 n_results: Number of results to return
384 category: Optional category filter
385
386 Returns:
387 List of matching memories with similarity scores
388 """
389 where_filter = {"category": category} if category else None
390
391 results = self.collection.query(
392 query_texts=[query],
393 n_results=n_results,
394 where=where_filter,
395 include=["documents", "metadatas", "distances"]
396 )
397
398 memories = []
399 for doc, meta, dist in zip(
400 results["documents"][0],
401 results["metadatas"][0],
402 results["distances"][0]
403 ):
404 memories.append({
405 "content": doc,
406 "category": meta.get("category"),
407 "similarity": 1 - dist, # Convert distance to similarity
408 "created_at": meta.get("created_at"),
409 })
410
411 return memories
412
413 def forget(self, memory_id: str) -> None:
414 """Delete a specific memory.
415
416 Args:
417 memory_id: ID of the memory to remove
418 """
419 self.collection.delete(ids=[memory_id])
420
421 def count(self) -> int:
422 """Return total number of stored memories."""
423 return self.collection.count()
424```
425
426## Examples
427
428### Example 1: Add persistent memory to a Claude Code agent
429
430**User prompt:** "Set up a memory system for my coding agent so it remembers project decisions, coding preferences, and lessons learned between sessions."
431
432The agent will:
433
434- Create a memory/ directory structure with MEMORY.md, daily logs, and entity files
435- Implement the FileMemory class with search and consolidation
436- Add session start hook that loads recent context (last 3 days + long-term memory)
437- Add session end hook that saves key decisions and new information
438- Set up periodic consolidation from daily logs into long-term memory
439
440### Example 2: Build semantic search over past conversations
441
442**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."
443
444The agent will:
445
446- Set up SQLite database with embedding storage
447- Configure OpenAI text-embedding-3-small for low-cost vector generation
448- Build search function with cosine similarity ranking
449- Add automatic memory extraction from conversation turns
450- Implement relevance threshold to avoid surfacing weak matches
451
452### Example 3: Scale agent memory for a production chatbot
453
454**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."
455
456The agent will:
457
458- Deploy ChromaDB with persistent storage
459- Design memory schema: categories for tickets, solutions, customer prefs, product docs
460- Implement metadata filtering for fast category-scoped queries
461- Add memory deduplication to prevent storing near-identical entries
462- Build memory aging — reduce relevance weight for old memories
463
464## Guidelines
465
466- **Start with file-based memory** — it works everywhere, has zero dependencies, and is human-readable
467- **Use embeddings when keyword search fails** — "deployment issues" should find "CI/CD pipeline broken"
468- **Consolidate regularly** — daily logs accumulate noise; distill into long-term memory weekly
469- **Category separation matters** — searching "preferences" shouldn't return "bug reports"
470- **Set memory limits** — without pruning, memory grows until it overwhelms context windows
471- **Privacy by default** — never store API keys, passwords, or PII in memory files
472- **Test recall quality** — bad embeddings return irrelevant results; validate with real queries
473- **Embedding cost** — text-embedding-3-small is $0.02/1M tokens; budget ~1M tokens/month for active agents
474- **ChromaDB vs Pinecone** — use ChromaDB for local/self-hosted, Pinecone for managed cloud at scale
475- **Memory injection** — prepend relevant memories to agent system prompt, not user messages
476