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

# 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

./scripts/save.sh "topic" "content" [tags...]

| Env | Default | Description | |-----|---------|-------------| | AGENT_MEMORY_DIR | ~/.agent-memory | Storage directory | | MEMORY_IMPORTANCE | normal | low / normal / high / critical |

# 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

./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

./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

./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

# 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

./scripts/daily.sh [YYYY-MM-DD] [--json]

topics.sh — Topic Index

./scripts/topics.sh [--json]

consolidate.sh — Topic Consolidation

./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

./scripts/stats.sh [--json]

Shows: total entries, date range, entries/day average, storage size, topic breakdown, importance distribution.

edit.sh — Edit or Delete

./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

./scripts/export.sh [-o backup.json] [--since YYYY-MM-DD] [--topic T]

import.sh — Import Memories

./scripts/import.sh backup.json [--dry-run]

Deduplicates by timestamp — safe to run multiple times.

prune.sh — Archive Old Memories

./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:

{"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

# 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 🔹