@tensakulabs/memory

A CLI for three-tier memory management (hot/warm/cold) with REM Sleep batch consolidation. Built for AI agents that need persistent, cost-efficient memory across sessions.

Install

bun add -g @tensakulabs/memory

Quick Start

# Create config at ~/.pai/memory/
memory init

# Edit the config for your agent
nano ~/.pai/memory/memory-config.json

# Stage a fact during a session ($0 cost)
memory stage "MiniMax M2.5 deployed as primary model on 2026-02-15"

# Run REM Sleep to batch-process staged facts
memory sleep --dry-run    # preview what would happen
memory sleep              # actually process

Commands

memory stage

Stage facts for later batch processing. Costs $0 — just appends to a local JSONL file.

memory stage "fact text"                            # auto-classify tier
memory stage "fact text" --tier cold                 # force tier
memory stage "fact text" --context "model research"  # add context
memory stage --list                                  # show pending facts
memory stage --count                                 # count pending

memory sleep

Run the REM Sleep batch processor. Classifies staged facts into tiers, deduplicates against mem0, and routes to the right storage.

memory sleep              # full run
memory sleep --dry-run    # preview decisions without executing
memory sleep --stats      # show staging statistics only

memory init

Create a config file at ~/.pai/memory/memory-config.json.

memory init               # default location
memory init --path ./     # custom location

memory config

Show current configuration and resolved paths.

Configuration

memory-config.json controls all behavior. Create from the example:

{
  "agent": "sage",
  "hot":  { "path": "~/.claude/projects/-Users-you/memory/MEMORY.md" },
  "warm": { "path": "./warm.jsonl" },
  "cold": {
    "mode": "mcp",
    "userId": "your-user-id"
  },
  "remSleep": {
    "maxColdWrites": 5,
    "dedupThreshold": 0.85,
    "stagingPath": "./rem-staging.jsonl"
  }
}

Config is found in this order:

1. --config flag
2. MEMORY_CONFIG env var
3. ~/.pai/memory/memory-config.json
4. ./memory-config.json

Cold Mode

| Mode | Use Case | How It Works | |------|----------|--------------| | mcp | Claude Code agents | Calls mem0 via claude -p MCP tools | | http | Standalone agents | Direct HTTP to mem0 REST API |

For HTTP mode, add "endpoint": "http://localhost:8080" to the cold config.

See examples/ for pre-made configs (Sage MCP, Atlas HTTP).

How It Works

Session                          Batch (REM Sleep)
───────                          ─────────────────
memory stage "fact" ──→ staging.jsonl ──→ classify ──→ hot (suggested)
                                                  ──→ warm (shared JSONL)
                                                  ──→ cold (mem0, deduplicated)

1. During sessions: memory stage "fact" appends to rem-staging.jsonl ($0)
2. REM Sleep runs periodically (cron, launchd, or manual memory sleep)
3. Each fact is classified by signal matching: hot / warm / cold
4. Cold candidates are deduplicated against mem0 (skip if >85% match)
5. Max 5 cold writes per run (~$0.005 max cost)
6. Hot facts are printed as suggestions — never auto-written

Memory Tiers

| Tier | Storage | TTL | Purpose | |------|---------|-----|---------| | Hot | Local MEMORY.md | Permanent | Agent-specific, always loaded | | Warm | Shared JSONL | 7 days | Cross-agent working context | | Cold | mem0 | Permanent | Long-tail semantic search |

Requirements

• Bun >= 1.0.0
• mem0 instance (for cold tier)
• Claude Code (for MCP mode) or direct mem0 API access (for HTTP mode)

License

MIT