Project-scoped memory for AI coding tools. Durable context across sessions with MCP integration, frames, smart retrieval, Claude Code skills, and automatic hooks.
npm install @stackmemoryai/stackmemory
Lossless, project-scoped memory for AI tools
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)
- Skills system with /spec and /linear-run for Claude Code
- Automatic hooks for task tracking, Linear sync, and spec progress
- 498 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.
---
Tools forget decisions and constraints between sessions. StackMemory makes context durable and actionable.
- Records: events, tool calls, decisions, and anchors
- Retrieves: high-signal context tailored to the current task
- Organizes: nested frames with importance scoring and shared stacks
---
- MCP tools for Claude Code: 26+ tools; context on every request
- Skills: /spec (iterative spec generation), /linear-run (task execution via RLM)
- Hooks: automatic context save, task tracking, Linear sync, PROMPT_PLAN updates
- Prompt Forge: watches AGENTS.md and CLAUDE.md for prompt optimization (GEPA)
- Safe branches: worktree isolation with --worktree or -w
- Persistent context: frames, anchors, decisions, retrieval
- Integrations: Linear, Greptile, DiffMem, Browser MCP
---
Requirements: Node >= 20
``bashInstall globally
npm install -g @stackmemoryai/stackmemory
Restart Claude Code and StackMemory MCP tools will be available.
---
Core concepts (quick mental model)
| Concept | Meaning |
| -------------- | ------------------------------------------------- |
| Project | One GitHub repo (initial scope) |
| Frame | A scoped unit of work (like a function call) |
| Call Stack | Nested frames; only the active path is "hot" |
| Event | Append-only record (message, tool call, decision) |
| Digest | Structured return value when a frame closes |
| Anchor | Pinned fact (DECISION, CONSTRAINT, INTERFACE) |
Frames can span:
- multiple chat turns
- multiple tool calls
- multiple sessions
---
Hosted vs Open Source
- Hosted: cloud-backed, fast retrieval, durable, team features — works out of the box.
- OSS local: SQLite, offline, inspectable — intentionally behind; no sync/org features.
---
How it integrates
Runs as an MCP server. Editors (e.g., Claude Code) call StackMemory on each interaction to fetch a compiled context bundle; editors don’t store memory themselves.
$3
Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are returned as a single text item containing JSON.
- Plan only (no code):
json
{"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-sonnet-4-20250514"}}}
`- Approval‑gated plan (phase 1):
json
{"method":"tools/call","params":{"name":"plan_gate","arguments":{"task":"Refactor config loader","compact":true}}}
`- Approve + execute (phase 2):
json
{"method":"tools/call","params":{"name":"approve_plan","arguments":{"approvalId":"","implementer":"codex","execute":true,"recordFrame":true,"compact":true}}}
`- Manage approvals:
json
{"method":"tools/call","params":{"name":"pending_list","arguments":{}}}
{"method":"tools/call","params":{"name":"pending_show","arguments":{"approvalId":"","compact":true}}}
{"method":"tools/call","params":{"name":"pending_clear","arguments":{"approvalId":""}}}
`Env defaults (optional):
-
(e.g., claude-sonnet-4-20250514)
- STACKMEMORY_MM_REVIEWER_MODEL (defaults to planner if unset)
- STACKMEMORY_MM_IMPLEMENTER (codex or claude)
- STACKMEMORY_MM_MAX_ITERS (e.g., 2)---
Skills System
StackMemory ships Claude Code skills that integrate directly into your workflow. Skills are invoked via
/skill-name in Claude Code or stackmemory skills from the CLI.$3
Generates iterative spec documents following a 4-doc progressive chain. Each document reads previous ones from disk for context.
`
ONE_PAGER.md → DEV_SPEC.md → PROMPT_PLAN.md → AGENTS.md
(standalone) (reads 1) (reads 1+2) (reads 1+2+3)
bash
Generate specs in order
/spec one-pager "My App" # Problem, audience, core flow, MVP
/spec dev-spec # Architecture, tech stack, APIs
/spec prompt-plan # TDD stages A-G with checkboxes
/spec agents # Agent guardrails and responsibilitiesManage progress
/spec list # Show existing specs
/spec update prompt-plan "auth" # Check off matching items
/spec validate prompt-plan # Check completion statusCLI equivalent
stackmemory skills spec one-pager "My App"
`Output goes to
. Use --force to regenerate an existing spec.$3
Pulls tasks from Linear, executes them via the RLM orchestrator (8 subagent types), and syncs results back.
`bash
/linear-run next # Execute next todo task
/linear-run next --priority high # Filter by priority
/linear-run all # Execute all pending tasks
/linear-run all --dry-run # Preview without executing
/linear-run task STA-123 # Run a specific task
/linear-run preview # Show execution planCLI equivalent
stackmemory ralph linear next
`On task completion:
1. Marks the Linear task as
2. Auto-checks matching PROMPT_PLAN items
3. Syncs metrics (tokens, cost, tests) back to LinearOptions:
, --tag , --dry-run, --maxConcurrent ---
Hooks (Automatic)
StackMemory installs Claude Code hooks that run automatically during your session. Hooks are non-blocking and fail silently to never interrupt your workflow.
$3
| Hook | Trigger | What it does |
|------|---------|-------------|
|
| Task marked done | Saves context, syncs Linear (STA-* tasks), auto-checks PROMPT_PLAN items |
| on-startup | Session start | Loads StackMemory context, initializes frame |
| on-clear | /clear command | Persists context before clearing |
| skill-eval | User prompt | Scores prompt against 28 skill patterns, recommends relevant skills |
| tool-use-trace | Tool invocation | Logs tool usage for context tracking |$3
When you type a prompt, the
skill-eval hook scores it against skill-rules.json (28 mapped skills with keyword, pattern, intent, and directory matching). Skills scoring above the threshold (default: 3) are recommended.`json
// Example: user types "generate a spec for the auth system"
// skill-eval recommends:
{
"recommendedSkills": [
{ "skillName": "spec-generator", "score": 8 },
{ "skillName": "frame-management", "score": 5 }
]
}
`$3
Hooks install automatically during
(with user consent). To install or reinstall manually:`bash
Automatic (prompted during npm install)
npm install -g @stackmemoryai/stackmemoryManual install
stackmemory hooks installSkip hooks (CI/non-interactive)
STACKMEMORY_AUTO_HOOKS=true npm install -g @stackmemoryai/stackmemory
`Hooks are stored in
and configured via ~/.claude/hooks.json.$3
When a task completes (via hook or
/linear-run), StackMemory fuzzy-matches the task title against unchecked - [ ] items in docs/specs/PROMPT_PLAN.md and checks them off automatically. One item per task completion, best-effort.---
Prompt Forge (GEPA)
When launching via
claude-sm, StackMemory watches CLAUDE.md, AGENT.md, and AGENTS.md for changes. On file modification, the GEPA optimizer analyzes content and suggests improvements for prompt clarity and structure. Runs as a detached background process.`bash
Launch with Prompt Forge active
claude-smStatus shown in terminal:
Prompt Forge: watching CLAUDE.md, AGENTS.md for optimization
`---
$3
bash
npm install -g @stackmemoryai/stackmemory@latest
`During install, you'll be asked if you want to install Claude Code hooks (optional but recommended).
$3
bash
cd your-project
stackmemory init
`This creates
with SQLite storage. No questions asked.For interactive setup with more options:
`bash
stackmemory init --interactive
`$3
bash
stackmemory setup-mcp
`This automatically:
- Creates
MCP configuration
- Updates ~/.claude/config.json with StackMemory integration
- Validates the configuration$3
`bash
stackmemory doctor
`Checks project initialization, database integrity, MCP config, and suggests fixes.
See docs/setup.md for advanced options (hosted mode, ChromaDB, manual MCP config).
---
Open-Source Local Mode
$3
bash
git clone https://github.com/stackmemoryai/stackmemory
cd stackmemory
npm install
npm run build
`$3
bash
npm run mcp:start
or for development
npm run mcp:dev
`This creates
with SQLite storage.$3
`json
{
"mcpServers": {
"stackmemory": {
"command": "node",
"args": ["dist/src/integrations/mcp/server.js"]
}
}
}
`How it works
Each interaction: ingests events → updates indices → retrieves relevant context → returns sized bundle.
---
Example MCP response (simplified)
json
{
"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"
]
}
`---
Storage & limits
$3
StackMemory implements an intelligent two-tier storage architecture:
#### Local Storage Tiers
- 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
#### Remote Storage
- 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
$3
- 1 project
- Up to 2GB local storage
- Up to 100GB retrieval egress / month
$3
- Per-project pricing
- Unlimited storage + retrieval
- Team sharing
- Org controls
- Custom retention policies
No seat-based pricing.
---
Claude Code Integration
StackMemory integrates with Claude Code via MCP tools, skills, and hooks. See the Hooks and Skills sections above.
bash
Full setup (one-time)
npm install -g @stackmemoryai/stackmemory # installs hooks automatically
cd your-project && stackmemory init # init project
stackmemory setup-mcp # configure MCP
stackmemory doctor # verify everything works
`Additional integration methods: shell wrapper (
), Linear auto-sync daemon, background daemon, git hooks. See docs/setup.md.RLM (Recursive Language Model) Orchestration
StackMemory includes an advanced RLM system that enables handling arbitrarily complex tasks through recursive decomposition and parallel execution using Claude Code's Task tool.
$3
- 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
$3
`bash
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 allExamples
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"
`$3
| Option | Description | Default |
|--------|-------------|---------|
|
| Maximum concurrent subagents | 5 |
| --max-recursion | Maximum recursion depth | 4 |
| --review-stages | Number of review iterations | 3 |
| --quality-threshold | Target quality score (0-1) | 0.85 |
| --test-mode | Test generation mode (unit/integration/e2e/all) | all |
| --verbose` | Show all recursive operations | false |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.
See https://github.com/stackmemoryai/stackmemory/blob/main/docs/cli.md for the full command reference and examples.
---
See https://github.com/stackmemoryai/stackmemory/blob/main/docs/status.md for current status.
---
See https://github.com/stackmemoryai/stackmemory/blob/main/docs/changelog.md for detailed release notes.
---
See https://github.com/stackmemoryai/stackmemory/blob/main/docs/roadmap.md for our current roadmap.
---
- 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
---