session-memory

用于人工智能代理的持久内存工具包。保存上下文、通过相关性评分回忆、巩固见解、跨会话跟踪决策。具有重要性级别、多关键字搜索、会话上下文加载器、导出/导入、内存统计信息。纯bash+node，无依赖。 v2.0.0

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

---

## 中文说明

# Session Memory 🧠 v2.0

为 AI 代理提供的持久记忆。保存重要内容，回忆相关内容，巩固你所学到的东西。

**v2.0：**相关性评分搜索、重要性级别、会话上下文加载器、巩固、导出/导入、统计、编辑/删除。

## 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 — 保存一条记忆

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

| Env | 默认值 | 描述 |
|-----|---------|-------------|
| `AGENT_MEMORY_DIR` | `~/.agent-memory` | 存储目录 |
| `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 — 搜索记忆

```bash
./scripts/recall.sh "query" [--json] [--limit N] [--topic T] [--importance I] [--since YYYY-MM-DD]
```

特性：
- **多关键字 AND 搜索** —— 所有词必须全部匹配
- **相关性评分** —— 基于词匹配比例 + 重要性 + 时间新近度
- **过滤器** —— 按主题、重要性级别、日期范围

```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 — 会话启动加载器

```bash
./scripts/context.sh [--days N] [--limit N] [--json]
```

为新会话加载最相关的记忆：
- 近期记忆（最近 N 天，默认 3 天）
- 无论新旧的 high/critical 重要性条目
- 先按重要性、再按新近度排序
- 按日期分组

```bash
# Quick context
./scripts/context.sh

# Wider window
./scripts/context.sh --days 7 --limit 30

# For programmatic use
./scripts/context.sh --json
```

### daily.sh — 单日视图

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

### topics.sh — 主题索引

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

### consolidate.sh — 主题巩固

```bash
./scripts/consolidate.sh [--since YYYY-MM-DD] [--topic T] [--json]
```

按主题对所有记忆进行分组，展示数量、日期范围、热门标签和最新条目。适用于周期性回顾。

### stats.sh — 记忆统计

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

展示：总条目数、日期范围、每天平均条目数、存储大小、主题分布、重要性分布。

### edit.sh — 编辑或删除

```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 — 导出记忆

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

### import.sh — 导入记忆

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

按时间戳去重 —— 多次运行也安全。

### prune.sh — 归档旧记忆

```bash
./scripts/prune.sh [days]
```

将早于 N 天（默认：30）的记忆移动到 `archive/`。

---

## Storage

```
~/.agent-memory/
├── 2026/
│   ├── 01/
│   │   ├── 15.jsonl
│   │   └── 16.jsonl
│   └── 02/
│       └── 01.jsonl
└── archive/          # Pruned memories
```

每一行都是一个 JSON 对象：
```json
{"ts":1706793600000,"topic":"decision","content":"Chose X because Y","tags":["project"],"importance":"high"}
```

## Importance Levels

| 级别 | 何时使用 | 行为 |