Session Memory

Persistent memory toolkit for AI agents. Save context, recall with relevance scoring, consolidate insights, track decisions across sessions. Features importa...

Security Scan

The skill's files and runtime instructions align with its described purpose (a local, file‑based session memory toolkit implemented in bash+node) and it does not request external credentials or network access, but it will store plaintext memories on disk so you should avoid saving secrets and protect the memory directory.

Purpose & Capability

Name/description (persistent session memory) match the provided scripts and SKILL.md. The code implements saving, searching, consolidating, exporting, importing, pruning, and stats using bash and node; requiring the 'node' binary is reasonable and proportionate.

Instruction Scope

SKILL.md instructs the agent to run local scripts that read/write JSONL files under AGENT_MEMORY_DIR (default ~/.agent-memory). The instructions stay within the memory domain (save/recall/context/etc.) but include examples that explicitly suggest storing credentials as 'critical' entries — the scripts do not encrypt or redact stored content, so following that example could lead to plain‑text secrets on disk.

Install Mechanism

There is no install spec (instruction-only skill) and no network download/install step. The repository includes only shell and node scripts; risk is limited to running those scripts locally. Requires node runtime which is declared and expected.

Credentials

The skill requests no environment variables or credentials. It does write and read local files (AGENT_MEMORY_DIR) and will process any JSONL files found there. While no extra permissions are requested, the capability to store arbitrary text (including secrets) in plaintext is a privacy concern and should be considered before use.

Persistence & Privilege

always:false and no persistent install actions are requested. The skill does not modify other skills or system settings; its persistence is limited to creating/reading/writing files under the designated memory directory.

Assessment

This skill appears to do what it says (local file‑based memory via bash+node). Before installing or running it: 1) Do NOT store API keys, passwords, or other secrets in memories — the files are plain JSONL and not encrypted. 2) Consider setting AGENT_MEMORY_DIR to a secure location and tighten filesystem permissions (e.g., chmod 700). 3) Review the scripts (they are human‑readable) if you plan to import/export data from untrusted sources. 4) Back up or encrypt sensitive memories externally if needed. 5) Avoid running these scripts as root or pointing AGENT_MEMORY_DIR to system directories. If you need encrypted storage or secret management, add encryption or integrate with a secrets manager before using for sensitive data.

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 🔹