--- name: agent-memory-ef2cc57912af 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 1.x, better-sqlite3, OpenAI API key for embeddings." metadata: author: terminal-skills version: "1.1.0" category: data-ai tags: "memory, embeddings, vector-search, context, rag" --- # Agent Memory ## Overview Coding agents start every session with an empty context window. This skill gives them memory that survives: first the file-based memory the agents themselves read (CLAUDE.md, AGENTS.md, GEMINI.md), then a small memory module you own (markdown files, SQLite with embeddings, or ChromaDB) for what instruction files cannot hold, such as thousands of past tickets or conversations searched by meaning. ## Instructions ### Step 0: Use the memory your agent already has Check this before building anything. Instruction files are loaded at the start of every session: | Agent | Persistent instructions | Notes | |-------|------------------------|-------| | Claude Code | `CLAUDE.md` (project, `~/.claude/CLAUDE.md`), `CLAUDE.local.md`, `.claude/rules/*.md` | Imports with `@docs/api.md`. Auto memory is on by default: Claude writes notes to `~/.claude/projects//memory/`, `MEMORY.md` is loaded at start (first 200 lines or 25KB). Browse or toggle with `/memory`; disable with `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`. | | OpenAI Codex | `AGENTS.md` (`~/.codex` and each directory from the repo root down), `AGENTS.override.md` | Combined size capped by `project_doc_max_bytes` (32 KiB). | | Gemini CLI | `GEMINI.md` (`~/.gemini/` and project directories) | `/memory show` and `/memory reload`; the file name can be changed with `context.fileName` (for example `AGENTS.md`). | If the request is "make the agent remember our conventions", write or extend those files and stop. Build the strategies below only for memory that is too large, too dynamic or must be searched semantically. ### Strategy 1: File-based memory (no dependencies) ``` memory/ MEMORY.md # curated long-term facts, kept short 2026-10-02.md # daily session logs decisions.md # key decisions and the reasoning ``` ```markdown # MEMORY.md ## Projects - Billing API: Node 22, Fastify, Postgres 16; deploys from the release branch ## Preferences - TypeScript strict mode; Vitest, not Jest; pnpm, not npm ## Lessons - Integration tests need Redis on localhost:6379 (docker compose up redis) ``` ```python # agent_memory.py from datetime import datetime, timedelta from pathlib import Path class FileMemory: def __init__(self, memory_dir: str = "memory"): self.dir = Path(memory_dir) self.dir.mkdir(parents=True, exist_ok=True) self.long_term = self.dir / "MEMORY.md" def log_today(self, content: str, section: str = "Notes") -> Path: daily = self.dir / f"{datetime.now():%Y-%m-%d}.md" if not daily.exists(): daily.write_text(f"# {daily.stem}\n") with daily.open("a") as f: f.write(f"\n## {section}\n{content}\n") return daily def remember(self, key: str, value: str, category: str = "General") -> None: text = self.long_term.read_text() if self.long_term.exists() else "# MEMORY.md\n" header = f"## {category}" if header not in text: text += f"\n{header}\n" pos = text.index(header) + len(header) + 1 self.long_term.write_text(text[:pos] + f"- **{key}**: {value}\n" + text[pos:]) def search(self, query: str, limit: int = 10) -> list[dict]: terms = query.lower().split() hits = [] for path in self.dir.rglob("*.md"): for n, line in enumerate(path.read_text().splitlines(), 1): score = sum(t in line.lower() for t in terms) / len(terms) if score: hits.append({"file": path.name, "line": n, "text": line.strip(), "score": score}) return sorted(hits, key=lambda h: h["score"], reverse=True)[:limit] def recent_context(self, days: int = 3) -> str: parts = [] for i in range(days): day = datetime.now() - timedelta(days=i) f = self.dir / f"{day:%Y-%m-%d}.md" if f.exists(): parts.append(f.read_text()) return "\n---\n".join(parts) ``` Consolidation: once a week, give `recent_context(days=7)` and the current `MEMORY.md` to the agent (or a local model) and ask it to merge durable facts, drop stale ones, and keep the file short enough to load fully each session. ### Strategy 2: SQLite plus embeddings (semantic search, one file) ```bash npm install better-sqlite3 openai export OPENAI_API_KEY="sk-proj-..." # from your secret manager, never committed ``` ```typescript // memory-store.ts import Database from "better-sqlite3"; import OpenAI from "openai"; export class MemoryStore { private db = new Database("agent-memory.db"); private openai = new OpenAI(); // reads OPENAI_API_KEY private model = "text-embedding-3-small"; constructor() { this.db.exec(`CREATE TABLE IF NOT EXISTS memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, category TEXT DEFAULT 'general', embedding BLOB NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP )`); } private async embed(text: string): Promise { const res = await this.openai.embeddings.create({ model: this.model, input: text }); return new Float32Array(res.data[0].embedding); } async store(content: string, category = "general"): Promise { const v = await this.embed(content); const blob = Buffer.from(v.buffer, v.byteOffset, v.byteLength); return Number(this.db.prepare( "INSERT INTO memories (content, category, embedding) VALUES (?, ?, ?)" ).run(content, category, blob).lastInsertRowid); } async search(query: string, limit = 5, minScore = 0.3) { const q = await this.embed(query); const rows = this.db.prepare( "SELECT content, category, embedding, created_at FROM memories ORDER BY id DESC LIMIT 5000" ).all() as { content: string; category: string; embedding: Buffer; created_at: string }[]; return rows .map((r) => { // a Buffer from SQLite can sit at a non-aligned offset inside a shared pool: copy the exact bytes const bytes = r.embedding.buffer.slice(r.embedding.byteOffset, r.embedding.byteOffset + r.embedding.byteLength); return { content: r.content, category: r.category, created_at: r.created_at, score: cosine(q, new Float32Array(bytes)) }; }) .filter((r) => r.score >= minScore) .sort((a, b) => b.score - a.score) .slice(0, limit); } } function cosine(a: Float32Array, b: Float32Array): number { let dot = 0, na = 0, nb = 0; for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] ** 2; nb += b[i] ** 2; } return dot / (Math.sqrt(na) * Math.sqrt(nb)); } ``` This scans rows in JavaScript, fine up to a few thousand memories. Beyond that, use an index (the `sqlite-vec` extension or Strategy 3). Store vectors from one model only; changing the embedding model means re-embedding everything. ### Strategy 3: ChromaDB (filtering and scale) ```bash python3 -m pip install chromadb # 1.x; the default embedder downloads a small ONNX model on first use ``` ```python # chroma_memory.py from datetime import datetime, timezone import chromadb class ChromaMemory: def __init__(self, path: str = "./chroma_db", name: str = "agent_memory"): self.client = chromadb.PersistentClient(path=path) self.col = self.client.get_or_create_collection( name, configuration={"hnsw": {"space": "cosine"}} # older code used metadata={"hnsw:space": ...} ) def store(self, memory_id: str, content: str, category: str = "general") -> None: # upsert: the same id overwrites instead of duplicating self.col.upsert(ids=[memory_id], documents=[content], metadatas=[ {"category": category, "created_at": datetime.now(timezone.utc).isoformat()}]) def recall(self, query: str, n: int = 5, category: str | None = None) -> list[dict]: r = self.col.query(query_texts=[query], n_results=n, where={"category": category} if category else None, include=["documents", "metadatas", "distances"]) return [{"content": d, "category": m["category"], "similarity": 1 - dist} for d, m, dist in zip(r["documents"][0], r["metadatas"][0], r["distances"][0])] def forget(self, memory_id: str) -> None: self.col.delete(ids=[memory_id]) ``` With cosine space, `distance = 1 - similarity`. A managed vector service (Pinecone, Qdrant Cloud) is the alternative when several machines or services must share one memory; the shape of `store` and `recall` stays the same. ### Injecting memory At session start, load `MEMORY.md` and `recent_context()`; before a task, run `recall(task_description)` and add the top three or four hits to the system prompt or the agent's instruction file, not to user messages. Show the source of each memory so the agent can judge how old it is. ## Examples ### Example 1: Remember project decisions between sessions **User prompt:** "My Codex and Claude Code agents keep forgetting that we use pnpm and that integration tests need Redis. Make them remember." The agent adds the two facts to `AGENTS.md` (read by Codex) and `CLAUDE.md` with `@AGENTS.md` imported, or runs `/memory` to confirm Claude's auto memory is on. It does not build a database. In a new session, asking "how do I run the tests?" answers with `pnpm test` and the Redis prerequisite without being told again. ### Example 2: Search past support tickets by meaning **User prompt:** "Our support bot has 40,000 resolved tickets. When a customer writes 'my invoice PDF is blank', it should find the earlier 'billing export renders empty' tickets." The agent creates a ChromaDB collection, loads each ticket with `store(f"ticket-{id}", text, category="billing")`, and calls `recall("my invoice PDF is blank", n=5, category="billing")`. The top results are the three earlier blank-export tickets each with its similarity score and resolution text, which the bot cites in its reply. ## Guidelines - Prefer the agent's own instruction files; they are loaded for free and humans review them in pull requests. - Keep always-loaded memory short (Claude Code loads about 200 lines of `MEMORY.md`, Codex 32 KiB of AGENTS.md); put detail in topic files and search it on demand. - Never store secrets, tokens or personal data in memory files or vector stores; memory is plain text and often committed or synced. - Memory goes stale: date entries, consolidate weekly, delete what is no longer true. A wrong memory is worse than none. - Test recall with real queries and set a minimum similarity so weak matches are not injected. - Embedding cost is small (text-embedding-3-small is priced per million tokens; check the current price) but every embedded memory is sent to the provider; use a local embedder for sensitive content. - Do not use vector search for fewer than a few hundred memories; grep over markdown is faster to debug. --- Source attribution: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/agent-memory/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to the Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by the Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding any notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS Copyright 2025 Terminal Skills Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Mega AI Hub resource metadata Creator / publisher: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/agent-memory/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Development & Engineering, Product Management Roles: Data Scientist, ML / AI Engineer, Product Manager, Technical Product Manager, Growth Product Manager Specialties: API, Backend Tools: Chromadb, Pinecone, OpenAI API Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: bba3d1fa0da41be90a7889905176b30c9334671e03b977dcc4520d34cc29aa5f