Persistent memory toolkit for AI agents. Save context, recall with relevance scoring, consolidate insights, track decisions across sessions. Features importa...
---
name: session-memory
description: Persistent memory toolkit for AI agents. Save context, recall with relevance scoring, consolidate insights, track decisions across sessions. Features importance levels, multi-keyword search, session context loader, export/import, memory stats. Pure bash+node, no dependencies. v2.0.0
homepage: https://github.com/voidborne-d/session-memory-skill
metadata: {"openclaw":{"emoji":"๐ง ","requires":{"bins":["node"]}}}
---
# Session Memory ๐ง v2.0
Persistent memory for AI agents. Save what matters, recall what's relevant, consolidate what you've learned.
**v2.0:** relevance-scored search, importance levels, session context loader, consolidation, export/import, stats, edit/delete.
## Quick Start
```bash
# Save a memory (with optional importance)
MEMORY_IMPORTANCE=high ./scripts/save.sh "decision" "Chose Postgres over SQLite for scale"
# Recall with relevance scoring
./scripts/recall.sh "database" --limit 5
# Load session context (startup)
./scripts/context.sh --days 3
# Consolidate by topic
./scripts/consolidate.sh --since 2026-01-01
# Stats
./scripts/stats.sh
```
---
## Commands
### save.sh โ Save a Memory
```bash
./scripts/save.sh "topic" "content" [tags...]
```
| Env | Default | Description |
|-----|---------|-------------|
| `AGENT_MEMORY_DIR` | `~/.agent-memory` | Storage directory |
| `MEMORY_IMPORTANCE` | `normal` | low / normal / high / critical |
```bash
# Basic save
./scripts/save.sh "insight" "Users prefer dark mode 3:1" ui design
# High importance
MEMORY_IMPORTANCE=high ./scripts/save.sh "decision" "Migrated to TypeScript" refactor
# Critical (always surfaces in context.sh)
MEMORY_IMPORTANCE=critical ./scripts/save.sh "credential" "API key rotated, new one in vault"
```
### recall.sh โ Search Memories
```bash
./scripts/recall.sh "query" [--json] [--limit N] [--topic T] [--importance I] [--since YYYY-MM-DD]
```
Features:
- **Multi-keyword AND search** โ all words must match
- **Relevance scoring** โ based on word match ratio + importance + recency
- **Filters** โ by topic, importance level, date range
```bash
./scripts/recall.sh "database migration"
./scripts/recall.sh "API" --topic decision --limit 20
./scripts/recall.sh "deploy" --since 2026-03-01 --json
./scripts/recall.sh "error" --importance high
```
### context.sh โ Session Startup Loader
```bash
./scripts/context.sh [--days N] [--limit N] [--json]
```
Loads the most relevant memories for a new session:
- Recent memories (last N days, default 3)
- High/critical importance items regardless of age
- Sorted by importance then recency
- Grouped by date
```bash
# Quick context
./scripts/context.sh
# Wider window
./scripts/context.sh --days 7 --limit 30
# For programmatic use
./scripts/context.sh --json
```
### daily.sh โ Day View
```bash
./scripts/daily.sh [YYYY-MM-DD] [--json]
```
### topics.sh โ Topic Index
```bash
./scripts/topics.sh [--json]
```
### consolidate.sh โ Topic Consolidation
```bash
./scripts/consolidate.sh [--since YYYY-MM-DD] [--topic T] [--json]
```
Groups all memories by topic, showing counts, date ranges, top tags, and latest entries. Useful for periodic review.
### stats.sh โ Memory Statistics
```bash
./scripts/stats.sh [--json]
```
Shows: total entries, date range, entries/day average, storage size, topic breakdown, importance distribution.
### edit.sh โ Edit or Delete
```bash
./scripts/edit.sh <timestamp_ms> --content "new content"
./scripts/edit.sh <timestamp_ms> --topic "new topic"
./scripts/edit.sh <timestamp_ms> --importance critical
./scripts/edit.sh <timestamp_ms> --delete
```
### export.sh โ Export Memories
```bash
./scripts/export.sh [-o backup.json] [--since YYYY-MM-DD] [--topic T]
```
### import.sh โ Import Memories
```bash
./scripts/import.sh backup.json [--dry-run]
```
Deduplicates by timestamp โ safe to run multiple times.
### prune.sh โ Archive Old Memories
```bash
./scripts/prune.sh [days]
```
Moves memories older than N days (default: 30) to `archive/`.
---
## Storage
```
~/.agent-memory/
โโโ 2026/
โ โโโ 01/
โ โ โโโ 15.jsonl
โ โ โโโ 16.jsonl
โ โโโ 02/
โ โโโ 01.jsonl
โโโ archive/ # Pruned memories
```
Each line is a JSON object:
```json
{"ts":1706793600000,"topic":"decision","content":"Chose X because Y","tags":["project"],"importance":"high"}
```
## Importance Levels
| Level | When to Use | Behavior |
|-------|-------------|----------|
| `low` | Background info, minor notes | Only found via search |
| `normal` | Standard memories | Shown in daily view |
| `high` | Key decisions, insights | Always in session context |
| `critical` | Credentials, blockers, urgent | Always in session context, top priority |
## Recommended Workflow
```bash
# Session start
./scripts/context.sh
# During work โ save important things
./scripts/save.sh "decision" "..."
MEMORY_IMPORTANCE=high ./scripts/save.sh "insight" "..."
# End of session
./scripts/save.sh "summary" "Today: did X, decided Y, next step Z"
# Weekly review
./scripts/consolidate.sh --since $(date -u -d '7 days ago' +%Y-%m-%d)
./scripts/stats.sh
# Monthly maintenance
./scripts/prune.sh 60
./scripts/export.sh -o backup-$(date +%Y%m).json
```
---
*Created by [Voidborne](https://voidborne.org) ๐น*
don't have the plugin yet? install it then click "run inline in claude" again.