playbooks

home / skills / openclaw / skills / agent-memory-persistence

agent-memory-persistence skill

/skills/imgolye/agent-memory-persistence

This skill provides durable memory persistence for AI agents using SQLite-backed storage, semantic retrieval, and lifecycle management across sessions.

npx playbooks add skill openclaw/skills --skill agent-memory-persistence

Review the files below or copy the command above to add this skill to your agents.

Files (11)
SKILL.md
1.5 KB
---
name: agent-memory-persistence
description: Provide long-term memory persistence for AI agents with SQLite-backed storage, structured metadata, vector embeddings, semantic retrieval, lifecycle management, and queries by user, session, and time.
---

# Agent Memory Persistence

Use this skill when an agent needs durable memory storage across sessions.

## What it provides

- SQLite-backed persistence for text, metadata, and embedding vectors
- CRUD operations for memory items
- Semantic retrieval with cosine-similarity vector search
- Memory lifecycle operations including expiration cleanup
- Filters by user, session, type, and time window

## Project structure

- `src/MemoryStore.ts`: low-level SQLite storage engine
- `src/VectorIndex.ts`: vector similarity search over stored embeddings
- `src/MemoryManager.ts`: high-level API used by agents
- `src/types.ts`: shared TypeScript contracts

## Usage pattern

1. Create a `MemoryManager` with a SQLite path.
2. Write memories with `content`, optional `metadata`, and optional `embedding`.
3. Query memories by session/user or use `searchByVector()` for semantic lookup.
4. Periodically call `cleanupExpired()` to delete stale memories.

## Notes

- Embeddings are stored as JSON arrays in SQLite.
- Vector search is implemented in TypeScript using cosine similarity, which keeps deployment simple and avoids SQLite extensions.
- If memory volume grows substantially, replace `VectorIndex` with an ANN index or SQLite vector extension while preserving the `MemoryManager` API.

Overview

This skill provides durable, SQLite-backed long-term memory persistence for AI agents, storing text, structured metadata, and embedding vectors. It combines CRUD operations, semantic retrieval via cosine-similarity, and lifecycle management so agents can recall and retire memories across sessions. It is implemented in a compact API suitable for Python integrations that need simple, reliable persistence without external vector DB dependencies.

How this skill works

The system stores each memory item in SQLite with content, optional metadata, and an embedding serialized as a JSON array. A VectorIndex performs in-process cosine-similarity searches over stored embeddings for semantic retrieval. A MemoryManager exposes high-level CRUD, query filters (by user, session, type, time), semantic search, and cleanup routines to expire stale memories.

When to use it

  • When agents must retain context across sessions or restarts
  • When you want semantic search over past agent observations without a separate vector DB
  • When you need per-user or per-session filtering of memories
  • When a lightweight, file-based storage solution is preferred
  • When you need straightforward lifecycle controls to expire old memories

Best practices

  • Provide embeddings at write-time when possible to enable fast semantic retrieval
  • Periodically run cleanupExpired() to keep the DB size controlled
  • Store concise metadata for efficient filtering (user, session, type, timestamp)
  • Monitor growth; migrate to an ANN index or SQLite vector extension if volume or latency becomes an issue
  • Keep embedding dimensionality consistent to avoid search errors

Example use cases

  • Personal assistant that remembers user preferences and past requests across sessions
  • Customer support agent that retrieves recent interactions and case notes semantically
  • Task automation bots that recall state, checkpoints, or prior decisions by session
  • Research agents that archive observations and perform semantic lookups over prior findings
  • Prototyping systems where a simple file-backed vector store accelerates development

FAQ

How are embeddings stored?

Embeddings are serialized as JSON arrays in SQLite rows so they remain portable and easy to inspect.

Can I search memories semantically without embedding every item?

Yes; semantic search works for items with embeddings. Items without embeddings can still be filtered by metadata and timestamp.