# StackMemory
[](https://github.com/stackmemoryai/stackmemory/actions/workflows/test-shared-context.yml)
[](https://github.com/stackmemoryai/stackmemory/actions/workflows/npm-publish.yml)
[](https://codecov.io/gh/stackmemoryai/stackmemory)
[](https://www.npmjs.com/package/@stackmemoryai/stackmemory)
Lossless, project-scoped memory for AI coding tools. **[Website](https://stackmemoryai.github.io/stackmemory/)** | **[MCP Tools](https://stackmemoryai.github.io/stackmemory/tools.html)** | **[Getting Started](./docs/GETTING_STARTED.md)**
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
- **73 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team, planning, providers, and more)
- **FTS5 full-text search** with BM25 scoring and hybrid retrieval
- **Full Linear integration** with bidirectional sync and OAuth/API key support
- **Context persistence** that survives `/clear` operations
- **Hierarchical frame organization** (nested call stack model)
- **Multi-wrapper support** — `claude-sm`, `codex-sm`, `opencode-sm` with auto context loading
- **Skills system** with `/spec` and `/linear-run` for Claude Code
- **Automatic hooks** for task tracking, Linear sync, and spec progress
- **Snapshot capture** — post-run context snapshots for session handoff (`snapshot save`)
- **Pre-flight overlap check** — predict file conflicts before parallel task dispatch (`preflight`)
- **Conductor orchestrator** — polls Linear, creates worktrees, spawns agents with bounded concurrency and auto team detection
- **Loop/Watch command** — poll any shell command until a condition is met (monitor CI, deploys, logs)
- **Memory monitor daemon** with automatic capture/clear on RAM pressure
- **Auto-save service** for periodic context persistence
- **Comprehensive test coverage** across all core modules
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.**
---
## Who is this for?
| You are... | StackMemory helps you... |
|------------|--------------------------|
| **Solo dev using Claude Code** | Keep decisions, constraints, and progress across sessions — no more re-explaining context after `/clear` |
| **Team using AI coding tools** | Share project context across agents and teammates with a single source of truth |
| **AI-first startup** | Ship faster with persistent memory, automatic Linear sync, and recursive task orchestration |
| **Open-source maintainer** | Onboard contributors and AI agents with durable project knowledge |
If you use an LLM coding assistant and lose context between sessions, StackMemory fixes that.
---
## Why StackMemory exists
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
---
## Features
- **MCP tools** for Claude Code: 56 tools across context, tasks, Linear, traces, planning, discovery, cord, team, and more
- **FTS5 search**: full-text search with BM25 scoring, hybrid retrieval, and smart thresholds
- **Skills**: `/spec` (iterative spec generation), `/linear-run` (task execution via RLM)
- **Hooks**: automatic context save, task tracking, Linear sync, PROMPT_PLAN updates, cord tracing
- **Prompt Forge**: watches CLAUDE.md and AGENTS.md for prompt optimization (GEPA)
- **Safe branches**: worktree isolation with `--worktree` or `-w`
- **Snapshot**: post-run context capture — records what changed, commits, and decisions (`stackmemory snapshot`)
- **Pre-flight check**: file overlap prediction before parallel task dispatch (`stackmemory preflight`)
- **Loop/Watch**: poll shell commands until conditions are met — monitor CI, deploys, logs (`stackmemory loop`)
- **Conductor**: autonomous orchestrator — polls Linear, creates worktrees, spawns agents with auto team detection
- **Persistent context**: frames, anchors, decisions, retrieval
- **Integrations**: Linear (API key + OAuth), DiffMem, Browser MCP, log-mcp (log analysis)
---
## Quick Start
Requirements: Node >= 20
```bash
# Install globally
npm install -g @stackmemoryai/stackmemory
# Initialize in your project (zero-config)
cd your-project
stackmemory init
# Configure Claude Code integration
stackmemory setup-mcp
# Verify everything works
stackmemory doctor
```
Restart Claude Code and StackMemory MCP tools will be available.
### Also available as `croissant-ai`
[croissant.ai](https://croissant.ai) wraps StackMemory as a business-facing CLI for executive intelligence. Install via `npx croissant-ai` — all unknown commands forward to StackMemory automatically.
```bash
npx croissant-ai ask "What's our MRR?" # croissant.ai query API
npx croissant-ai memory capture # → stackmemory capture
npx croissant-ai init # → stackmemory init (fallback)
```
### Wrapper Scripts
StackMemory ships wrapper scripts that launch your coding tool with StackMemory context pre-loaded:
```bash
claude-sm # Claude Code with StackMemory context + Prompt Forge
claude-smd # Claude Code with --dangerously-skip-permissions
codex-sm # Codex with StackMemory context
codex-smd # Codex with --dangerously-skip-permissions
opencode-sm # OpenCode with StackMemory context
```
---
## Core Concepts
| 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, tool calls, and sessions.
---
## 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.
---
## Command Packs
StackMemory ships installable command packs for Claude Code — curated slash commands that integrate session lifecycle management directly into your workflow.
### Core Pack
The **core** pack provides session lifecycle commands that use StackMemory for context persistence:
| Command | Description |
|---------|-------------|
| `/start` | Boot a session — load memory, restore handoff, show git state, suggest next work |
| `/stop` | End a session — summarize, capture handoff, review learnings |
| `/restart` | Chain `/stop` → `/clear` → `/start` in one command |
| `/next` | Suggest what to work on based on context |
Internal dependencies (installed automatically): `/summary`, `/capture`, `/learn`, `/restore`
```bash
# Install core commands
stackmemory setup-commands
# List available packs
stackmemory setup-commands --list
# Preview what would be installed
stackmemory setup-commands --dry-run
# Reinstall (overwrite existing)
stackmemory setup-commands --force
# Remove installed commands
stackmemory setup-commands --uninstall
```
Commands are symlinked to `~/.claude/commands/` and available immediately in Claude Code.
---
## 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.
### Spec Generator (`/spec`)
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 responsibilities
# Manage progress
/spec list # Show existing specs
/spec update prompt-plan "auth" # Check off matching items
/spec validate prompt-plan # Check completion status
# CLI equivalent
stackmemory skills spec one-pager "My App"
```
Output goes to `docs/specs/`. Use `--force` to regenerate an existing spec.
### Linear Task Runner (`/linear-run`)
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 plan
# CLI equivalent
stackmemory ralph linear next
```
On task completion:
1. Marks the Linear task as `done`
2. Auto-checks matching PROMPT_PLAN items
3. Syncs metrics (tokens, cost, tests) back to Linear
Options: `--priority `, `--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.
### Installed Hooks
| Hook | Trigger | What it does |
|------|---------|-------------|
| `on-task-complete` | 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 |
### Hook Installation
Hooks install automatically during `npm install` (with user consent). To install or reinstall manually:
```bash
# Automatic (prompted during npm install)
npm install -g @stackmemoryai/stackmemory
# Manual install
stackmemory hooks install
# Skip hooks (CI/non-interactive)
STACKMEMORY_AUTO_HOOKS=true npm install -g @stackmemoryai/stackmemory
```
Hooks are stored in `~/.claude/hooks/` and configured via `~/.claude/hooks.json`.
### PROMPT_PLAN Auto-Progress
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.
---
## Memory Monitor Daemon
Automatically monitors system RAM and Node.js heap usage, triggering capture/clear cycles when memory pressure exceeds thresholds. Prevents long-running sessions from degrading performance.
### How it works
1. Daemon checks RAM and heap usage every 30 seconds
2. If either exceeds 90%, it captures context (`stackmemory capture --no-commit --basic`)
3. Clears context (`stackmemory clear --save`)
4. Writes a signal file (`.stackmemory/.memory-clear-signal`)
5. On next prompt, a Claude Code hook reads the signal and alerts you to run `/clear`
### Configuration
Configured via `stackmemory daemon` with these defaults:
| Option | Default | Description |
|--------|---------|-------------|
| `ramThreshold` | 0.9 (90%) | System RAM usage trigger |
| `heapThreshold` | 0.9 (90%) | Node.js heap usage trigger |
| `cooldownMinutes` | 10 | Minimum time between triggers |
| `interval` | 0.5 (30s) | Check frequency in minutes |
### CLI
```bash
stackmemory daemon start # Start daemon (includes memory monitor)
stackmemory daemon status # Show memory stats, trigger count, thresholds
stackmemory daemon stop # Stop daemon
```
---
## 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-sm
# Status shown in terminal:
# Prompt Forge: watching CLAUDE.md, AGENTS.md for optimization
```
---
## RLM-Aware Harness
StackMemory includes an RLM (Recursive Language Model) system inspired by [predict-rlm](https://github.com/Trampoline-AI/predict-rlm) — three layers that make agents self-harnessing:
### Layer 1: Context-as-REPL
Agents access tenant data programmatically via tool functions instead of prose handoffs:
- `search_knowledge(query, topK)` — vector search over tenant data
- `read_context(query)` — knowledge graph entity/relationship queries
- `list_runs(threadId)` — prior run history with status summaries
- `get_run_events(runId)` — event stream replay for a specific run
- `query_interrupts(threadId)` — pending approvals and blocks
- `llm_summarize(prompt)` — sub-LLM (Haiku) for quick synthesis
### Layer 2: Typed Dispatch
Signature-based sub-agent spawning with validated I/O contracts:
| Signature | Persona | Inputs | Outputs |
|-----------|---------|--------|---------|
| `ImplementFeature` | eng | spec, context_files | branch, changed_files, test_passed |
| `FixBug` | eng | description, error_log | branch, changed_files, root_cause |
| `ReviewPR` | eng | pr_url, focus_areas | verdict, comments, risk_level |
| `Investigate` | data | question, data_sources | findings, evidence, confidence |
| `Summarize` | data | content, format | summary, key_points |
Parent runs dispatch typed sub-runs via `dispatchSubRun()` and collect validated results via `collectSubRun()` with timeout handling.
### Layer 3: Critic + Self-Decomposition
LLM quality gate that evaluates run output (ported from predict-rlm's critic pattern):
- **Score >= 80**: Pass — run ships as-is
- **Score 50-79**: Revise — creates a new run with critic feedback appended
- **Score < 50**: Decompose — dispatches typed sub-runs to break down the task
Loop control: max 3 revisions, max depth 2 for decomposition.
### Legacy RLM Orchestrator
The original RLM system remains available for direct use:
```bash
stackmemory skills rlm "Your complex task description"
stackmemory skills rlm "Refactor auth" --max-parallel 8 --quality-threshold 0.9
```
| Option | Description | Default |
|--------|-------------|---------|
| `--max-parallel` | 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 |
**Note**: RLM requires Claude Code Max plan for unlimited subagent execution.
---
## Open-Source Local Mode
### Step 1: Clone & Build
```bash
git clone https://github.com/stackmemoryai/stackmemory
cd stackmemory
npm install
npm run build
```
### Step 2: Run local MCP server
```bash
npm run mcp:start
# or for development
npm run mcp:dev
```
### Step 3: Point your editor to local MCP
```json
{
"mcpServers": {
"stackmemory": {
"command": "node",
"args": ["dist/src/integrations/mcp/server.js"]
}
}
}
```
---
## Guarantees & Non-goals
**Guarantees:** Lossless storage, project isolation, survives session/model switches, inspectable local mirror.
**Non-goals:** Chat UI, vector DB replacement, tool runtime, prompt framework.
---
## CLI Commands
See [docs/cli.md](https://github.com/stackmemoryai/stackmemory/blob/main/docs/cli.md) for the full command reference.
### Snapshot (`snapshot` / `snap`)
Capture a point-in-time snapshot of what changed on your branch — files modified, commits, and key decisions. Useful for session handoff and post-task review.
```bash
# Save a snapshot of current branch state
stackmemory snapshot save --task "add auth middleware"
# Save with explicit decisions
stackmemory snap save -d "chose JWT over session cookies" -d "switched to argon2"
# List recent snapshots
stackmemory snap list
# Show latest snapshot (or by branch)
stackmemory snap show feature/auth
```
### Pre-flight Check (`preflight` / `pf`)
Predict file overlaps before running parallel tasks. Uses git history, import graphs, and keyword matching to flag conflicts.
```bash
# Check if two tasks can safely run in parallel
stackmemory preflight "add user auth" "refactor database layer"
# With explicit file hints
stackmemory pf "auth work" "db migration" -f "task1:src/auth.ts;task2:src/db.ts"
# JSON output for programmatic use
stackmemory pf "task A" "task B" "task C" --json
```
### Loop / Watch (`loop` / `watch`)
Poll a shell command until a condition is met. Useful for monitoring CI runs, deploy logs, inboxes, or any external state.
```bash
# Monitor GitHub Actions until complete
stackmemory loop "gh run view --json status -q .status" --until "completed"
# Watch deploy logs for success
stackmemory watch "railway logs --latest" --until "deployed" -i 5s
# Wait for health check to pass
stackmemory loop "curl -s http://localhost:3000/health" --until "ok" -i 3s -t 5m
# JSON output for programmatic use
stackmemory loop "gh pr checks 42 --json state -q '.[0].state'" --until "SUCCESS" --json
```
Options: `--until`, `--until-not`, `--until-empty`, `--until-non-empty`, `--until-exit`, `-i/--interval` (default 10s), `-t/--timeout` (default 30m), `--json`, `-q/--quiet`
---
## Documentation
- [Getting Started](./docs/GETTING_STARTED.md) — Quick start guide (5 minutes)
- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 73 MCP tools
- [CLI Reference](./docs/cli.md) — Full command reference
- [Setup Guide](./docs/SETUP.md) — Advanced setup options
- [Development Guide](./docs/DEVELOPMENT.md) — Contributing and development
- [Architecture](./docs/architecture.md) — System design
- [API Reference](./docs/API_REFERENCE.md) — API documentation
- [Vision](./docs/vision.md) — Product vision and principles
- [Status](./docs/status.md) — Current project status
- [Roadmap](./docs/roadmap.md) — Future plans
---
## Substrate: The Three-Layer Vision
StackMemory is the foundation of a three-layer architecture for AI-native development:
| Layer | Product | Status | Purpose |
|-------|---------|--------|---------|
| **L1** | StackMemory | Shipped (v1.10.6) | Context persistence — lossless memory across sessions |
| **L2** | Substrate Desktop | Shipping | Agent orchestration — multi-agent coordination with worktree isolation |
| **L3** | Substrate Cloud | Design | Multiplayer development — shared context across teams and agents |
Grounded in distributed systems theory: FLP impossibility, Byzantine→Crash conversion via test hooks, Chandra-Toueg failure detectors for agent liveness. See [COORDINATION_THEORY.md](./docs/architecture/COORDINATION_THEORY.md).
---
## License
Licensed under the [PolyForm Noncommercial License 1.0.0](./LICENSE).
Free for personal, research, educational, and noncommercial use. Commercial use requires a separate license from StackMemory AI.