Lossless, project-scoped memory for AI tools • v0.5.47

StackMemory is a production-ready memory runtime for AI coding tools that preserves full project context across sessions:

• Zero-config setup - stackmemory init just works, no questions asked
• 26 MCP tools for Claude Code integration
• Full Linear integration with bidirectional sync
• Context persistence that survives /clear operations
• Hierarchical frame organization (nested call stack model)
• 490 tests passing with comprehensive coverage

Instead of a linear chat log, StackMemory organizes memory as a call stack of scoped work (frames), with intelligent LLM-driven retrieval and team collaboration features.

Memory is storage. Context is a compiled view.

Development tools lose context between sessions:

• Previous decisions aren't tracked
• Constraints get forgotten
• Changes lack history
• Tool execution isn't recorded

StackMemory solves this by:

• Storing all events, tool calls, and decisions
• Smart retrieval of relevant context
• Call stack organization for nested context
• Configurable importance scoring
• Team collaboration through shared stacks

Frames can span:

• multiple chat turns
• multiple tool calls
• multiple sessions

• Cloud-backed memory runtime
• Fast indexing + retrieval
• Durable storage
• Per-project pricing
• Works out-of-the-box

• SQLite-based
• Fully inspectable
• Offline / air-gapped
• Intentionally N versions behind
• No sync, no org features

OSS is for trust and inspection. Hosted is for scale, performance, and teams.

StackMemory integrates as an MCP tool and is invoked on every interaction in:

• Claude Code
• compatible editors
• future MCP-enabled tools

The editor never manages memory directly; it asks StackMemory for the context bundle.

# Install globally
npm install -g @stackmemoryai/stackmemory

# Initialize in your project (zero-config, just works)
cd your-project
stackmemory init

# Configure Claude Code integration
stackmemory setup-mcp

# Verify everything works
stackmemory doctor

That's it! Restart Claude Code and StackMemory MCP tools are available.

npm install -g @stackmemoryai/stackmemory@latest

During install, you'll be asked if you want to install Claude Code hooks (optional but recommended).

cd your-project
stackmemory init

This creates .stackmemory/ with SQLite storage. No questions asked.

For interactive setup with more options:

stackmemory init --interactive

stackmemory setup-mcp

This automatically:

• Creates ~/.claude/stackmemory-mcp.json MCP configuration
• Updates ~/.claude/config.json with StackMemory integration
• Validates the configuration

stackmemory doctor

Checks project initialization, database integrity, MCP config, and suggests fixes.

mkdir -p ~/.claude
cat > ~/.claude/stackmemory-mcp.json << 'EOF'
{
  "mcpServers": {
    "stackmemory": {
      "command": "stackmemory",
      "args": ["mcp-server"],
      "env": { "NODE_ENV": "production" }
    }
  }
}
EOF

{
  "mcp": {
    "configFiles": ["~/.claude/stackmemory-mcp.json"]
  }
}

stackmemory onboard
# Select "Hosted" when prompted
# Or set DATABASE_URL environment variable

stackmemory init --chromadb
# Prompts for ChromaDB API key

Claude Code sessions automatically capture tool calls, maintain context across sessions, and sync with Linear when configured.

Available MCP tools in Claude Code:

git clone https://github.com/stackmemoryai/stackmemory
cd stackmemory
npm install
npm run build

npm run mcp:start
# or for development
npm run mcp:dev

This creates .stackmemory/ with SQLite storage.

{
  "mcpServers": {
    "stackmemory": {
      "command": "node",
      "args": ["dist/integrations/mcp/server.js"]
    }
  }
}

Each interaction: ingests events → updates indices → retrieves relevant context → returns sized bundle.

{
  "hot_stack": [
    { "frame": "Debug auth redirect", "constraints": [...] }
  ],
  "anchors": [
    { "type": "DECISION", "text": "Use SameSite=Lax cookies" }
  ],
  "relevant_digests": [
    { "frame": "Initial auth refactor", "summary": "..." }
  ],
  "pointers": [
    "s3://logs/auth-test-0421"
  ]
}

StackMemory implements an intelligent two-tier storage architecture:

• Young (<24h): Uncompressed, complete retention in memory/Redis
• Mature (1-7d): LZ4 compression (~2.5x), selective retention
• Old (7-30d): ZSTD compression (~3.5x), critical data only

• Archive (>30d): Infinite retention in S3 + TimeSeries DB
• Migration: Automatic background migration based on age, size, and importance
• Offline Queue: Persistent retry logic for failed uploads

• 1 project
• Up to 2GB local storage
• Up to 100GB retrieval egress / month

• Per-project pricing
• Unlimited storage + retrieval
• Team sharing
• Org controls
• Custom retention policies

No seat-based pricing.

StackMemory can automatically save context when using Claude Code, so your AI assistant has access to previous context and decisions.

# Add alias
echo 'alias claude="~/Dev/stackmemory/scripts/claude-code-wrapper.sh"' >> ~/.zshrc
source ~/.zshrc

# Use: claude (saves context on exit)

# 1. Shell wrapper (recommended)
claude [--auto-sync] [--sync-interval=10]

# 2. Linear auto-sync daemon
./scripts/linear-auto-sync.sh start [interval]

# 3. Background daemon
./scripts/stackmemory-daemon.sh [interval] &

# 4. Git hooks
./scripts/setup-git-hooks.sh

Features: Auto-save on exit, Linear sync, runs only in StackMemory projects, configurable sync intervals.

StackMemory includes an advanced RLM system that enables handling arbitrarily complex tasks through recursive decomposition and parallel execution using Claude Code's Task tool.

• Recursive Task Decomposition: Breaks complex tasks into manageable subtasks
• Parallel Subagent Execution: Run multiple specialized agents concurrently
• 8 Specialized Agent Types: Planning, Code, Testing, Linting, Review, Improve, Context, Publish
• Multi-Stage Review: Iterative improvement cycles with quality scoring (0-1 scale)
• Automatic Test Generation: Unit, integration, and E2E test creation
• Full Transparency: Complete execution tree visualization

# Basic usage
stackmemory skills rlm "Your complex task description"

# With options
stackmemory skills rlm "Refactor authentication system" \
  --max-parallel 8 \
  --review-stages 5 \
  --quality-threshold 0.9 \
  --test-mode all

# Examples
stackmemory skills rlm "Generate comprehensive tests for API endpoints"
stackmemory skills rlm "Refactor the entire authentication system to use JWT"
stackmemory skills rlm "Build, test, and publish version 2.0.0"

1. Task Decomposition: Planning agent analyzes the task and creates a dependency graph
2. Parallel Execution: Independent subtasks run concurrently up to the parallel limit
3. Review Cycle: Review agents assess quality, improve agents implement fixes
4. Test Generation: Testing agents create comprehensive test suites
5. Result Aggregation: All outputs are combined into a final deliverable

Note: RLM requires Claude Code Max plan for unlimited subagent execution. In development mode, it uses mock responses for testing.

Guarantees: Lossless storage, project isolation, survives session/model switches, inspectable local mirror.

Non-goals: Chat UI, vector DB replacement, tool runtime, prompt framework.

# Setup & Diagnostics
stackmemory init                          # Initialize project (zero-config)
stackmemory init --interactive            # Interactive setup with options
stackmemory setup-mcp                     # Configure Claude Code MCP
stackmemory doctor                        # Diagnose issues and suggest fixes

# Status
stackmemory status                        # Current status
stackmemory progress                      # Recent activity

# Tasks
stackmemory tasks list [--status pending] # List tasks
stackmemory task add "title" --priority high
stackmemory task done <id>

# Search & Logs
stackmemory search "query" [--tasks|--context]
stackmemory log [--follow] [--type task]

# Context
stackmemory context show [--verbose]
stackmemory context push "name" --type task
stackmemory context add decision "text"
stackmemory context pop [--all]

# Linear Integration
stackmemory linear setup                  # OAuth setup
stackmemory linear sync [--direction from_linear]
stackmemory linear auto-sync --start
stackmemory linear update ENG-123 --status done

# Storage Management
stackmemory storage status               # Show tier distribution
stackmemory storage migrate [--tier young] # Trigger migration
stackmemory storage cleanup --force      # Clean old data
stackmemory storage config --show        # Show configuration

# Analytics & Server
stackmemory analytics [--view|--port 3000]
stackmemory mcp-server [--port 3001]

• Hosted: Private beta
• OSS mirror: Production ready
• MCP integration: Stable
• CLI: v0.5.47 - Zero-config setup, diagnostics, full task/context/Linear management
• Two-tier storage: Complete
• Test Suite: 490 tests passing

• Graceful database failures: Handles native module version mismatches
• Suppress dotenv logs: Cleaner terminal output
• TTY preservation: Fixes interactive mode for claude-sm/claude-smd
• Silent Linear auth: No spam when API key not configured

• Zero-config onboarding: stackmemory init now works without any prompts
• New setup-mcp command: Auto-configures Claude Code MCP integration
• New doctor command: Diagnoses issues and suggests fixes
• Interactive postinstall: Asks for consent before modifying ~/.claude
• Better error messages: Shows reason + fix + next step

• AsyncMutex: Thread-safe Linear sync with stale lock detection
• Action timeout: 60s timeout for SMS action execution
• Persistent rate limiting: Survives server restarts
• Atomic file writes: Prevents corruption on crash

• Standardized error handling with IntegrationError, DatabaseError, ValidationError
• Adopted error classes across Linear integration (12 files)
• Adopted error classes across database layer (6 files)
• WhatsApp notifications with session ID and interactive options

• WhatsApp flag for claude-sm automatic notifications
• Incoming request queue for WhatsApp triggers
• SMS webhook /send endpoint for outgoing notifications

• OpenCode wrapper (opencode-sm) with context integration
• Discovery CLI and MCP tools
• Real LLM provider and retrieval audit system
• Linear issue management and task picker

• Claude-sm remote mode and configurable defaults
• Context loading command improvements
• Session summary features

• Fixed critical error handling - getFrame() returns undefined instead of throwing
• Improved test coverage and fixed StackMemoryError constructor usage
• Removed dangerous secret-cleaning scripts from repository
• All tests passing, lint clean, build successful

• Two-tier storage system implementation complete
• Smart compression with LZ4/ZSTD support
• Background migration with configurable triggers
• Improved Linear integration with bidirectional sync

Phase 4 (Completed): Two-tier storage system with local tiers and infinite remote storage Phase 5 (Current): PostgreSQL production adapter, enhanced team collaboration, advanced analytics Phase 6 (Next): Enterprise features, multi-org support, cost optimization

• Hosted service: Proprietary
• Open-source mirror: Apache 2.0 / MIT (TBD)

• ML System Insights - Analysis of 300+ production ML systems
• Agent Instructions - Specific guidance for AI agents working with ML systems

• Product Requirements - Detailed product specifications
• Technical Architecture - System design and database schemas
• Beads Integration - Git-native memory patterns from Beads ecosystem