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

StackMemory is a production-ready memory runtime for AI coding tools that preserves full project context across sessions. With Phases 1-4 complete, it delivers:

• ✅ 89-98% faster task operations than manual tracking
• ✅ 10,000+ frame depth support with hierarchical organization
• ✅ Full Linear integration with bidirectional sync
• ✅ 20+ MCP tools for Claude Code
• ✅ Context persistence that survives /clear operations
• ✅ Two-tier storage system with local tiers and infinite remote storage
• ✅ Smart compression (LZ4/ZSTD) with 2.5-3.5x ratios
• ✅ Background migration with configurable triggers
• ✅ 296 tests passing with improved error handling
• ✅ npm v0.3.16 published with production-ready improvements

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 (10,000+ frame depth)
• 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.

Formula: (Test Coverage × 0.3) + (Performance × 0.3) + (Documentation × 0.2) + (Issues Resolution × 0.2)

1. [STA-289] Performance Optimization - Achieve SLA targets
2. [STA-291] Code Cleanup - Zero TODOs, 90% coverage

stackmemory projects create \
  --repo https://github.com/org/repo

This creates a project-scoped memory space tied to the repo.

npm install -g @stackmemoryai/stackmemory@0.3.16
# or latest
npm install -g @stackmemoryai/stackmemory@latest

# Automatic setup - configures MCP and session hooks
npm run claude:setup

This automatically:

• Creates ~/.claude/stackmemory-mcp.json MCP configuration
• Sets up session initialization hooks
• Updates ~/.claude/config.json with StackMemory integration

Manual setup alternative:

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"]
  }
}

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/stackmemory/stackmemory
cd stackmemory

cargo run --bin stackmemory-mcp
# or
npm run dev

This creates:

.memory/
  └── memory.db   # SQLite

All project memory lives locally.

{
  "tools": {
    "stackmemory": {
      "command": "stackmemory-mcp",
      "args": ["--local"]
    }
  }
}

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.

# Core
stackmemory init                          # Initialize project
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.3.16 - Full task, context, Linear, and storage management
• Two-tier storage: Complete
• Test Suite: 296 tests passing

• ✅ 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
• ✅ Published to npm with production-ready improvements

• ✅ 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 (Next): PostgreSQL production adapter, enhanced team collaboration, advanced analytics
Phase 3: Team collaboration, shared stacks, frame handoff
Phase 4: Two-tier storage, enterprise features, 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