@memstack/cli

@memstack/cli

CLI for MemStack — shell-based agent memory. Use from bash scripts, opencode/Claude Code shell tools, CI pipelines, or any subprocess-capable agent.

Installation

npm install -g @memstack/cli
# or
npx @memstack/cli [command]

Configuration

All via environment variables. Same scheme as @memstack/mcp.

Variable	Purpose	Default
MEMSTACK_STORAGE	Storage backend	memory
MEMSTACK_DIR	Directory for markdown/disk	./memories
DATABASE_URL	Postgres connection	—
SQLITE_PATH	SQLite database path	./memstack.db
REDIS_URL	Redis connection	redis://localhost:6379
OPENAI_API_KEY	OpenAI LLM + embeddings	—
ANTHROPIC_API_KEY	Anthropic LLM (summarization)	—
MEMSTACK_OPENAI_BASE_URL	Custom API endpoint (DeepSeek, etc.)	https://api.openai.com/v1
MEMSTACK_LLM_MODEL	Model override	gpt-4o-mini
MEMSTACK_EMBED_ON_STORE	Auto-embed on store	true

Commands

All output is JSON to stdout. Errors go to stderr.

store

memstack store --actor "agent-1" --content "User reported login bug" --type interaction --importance 0.8 --tags "bug,login"
# {"id":"mem_...","actorId":"agent-1","content":"User reported login bug",...}

retrieve

memstack retrieve --actor "agent-1" --query "login" --strategy hybrid --limit 5
memstack retrieve --actor "agent-1" --created-after "2026-01-01T00:00:00Z" --created-before "2026-06-01T00:00:00Z"

context

memstack context --actor "agent-1" --max-tokens 2000
# {"systemPrompt":"## Important Memories\n- ...", "tokenEstimate": 280, ...}

summarize

memstack summarize --actor "agent-1" --older-than 7d
# {"summary": {...}, "deletedCount": 47}

prune

memstack prune --actor "agent-1" --type byAge --max-age 30d
memstack prune --actor "agent-1" --type byImportance --min-importance 0.3
memstack prune --actor "agent-1" --type byCount --max-count 500
memstack prune --actor "agent-1" --type byAge --max-age 7d --dry-run  # preview only

purge

memstack purge --actor "agent-1"
# 42  (number of deleted memories)

merge

memstack merge --ids "mem_abc,mem_def,mem_ghi"
# {merged memory object}

stats

memstack stats --actor "agent-1"
# {"total":1500,"expired":3,"oldest":"...","newest":"...","avgImportance":0.6,...}

delete

memstack delete --id "mem_abc123"
# {"deleted":true}

health

memstack health
# {"storage":true,"llm":true,"embedding":true}

export

memstack export --actor "agent-1"
memstack export --actor "agent-1" --out ./backup.json
# {"saved":"./backup.json","count":1500}

import

memstack import --actor "agent-1" --file ./backup.json
# {"imported":1500}

Each memory's original createdAt is preserved on import (round-trips exactly with export). Importing a snapshot with zero memories fails cleanly with a non-zero exit.

Input validation

The CLI normalizes and validates input before storing:

• --importance is clamped to the 0.0–1.0 range (e.g. --importance 5 stores as 1, --importance=-1 stores as 0).
• --actor is trimmed of leading/trailing whitespace (--actor " a " and --actor a are the same actor).
• --tags drops empty entries from trailing/double commas (--tags "a,,b," → ["a","b"]).
• prune --type rejects unknown strategies with a non-zero exit instead of silently doing nothing. Valid: byAge, byImportance, byCount, byType, custom, compose.
• prune --actor is scoped to that actor only — it never touches other actors' memories.

Shell agent usage

#!/bin/bash
AGENT_ID="support-bot"

# Before each turn: inject memory context
CONTEXT=$(memstack context --actor "$AGENT_ID" --max-tokens 1500)
SYSTEM_PROMPT=$(echo "$CONTEXT" | jq -r '.systemPrompt')

# After each turn: store what happened
memstack store --actor "$AGENT_ID" --content "$TURN_SUMMARY" --type interaction

# Periodic maintenance
memstack prune --actor "$AGENT_ID" --type byAge --max-age 30d

Publishing

cd packages/cli
pnpm build && pnpm check && pnpm test
npm publish --access public

After publishing, users install with:

npm install -g @memstack/cli

License

MIT