Skip to content
statefulmemory

Getting started

This tour walks the main surfaces once. Each step links to a detailed guide.

1. Install the CLI

Section titled “1. Install the CLI”
Terminal window
brew install sanudatta11/tap/statefulmemory   # or build from source:
# git clone https://github.com/sanudatta11/statefulmemory && cd statefulmemory
# make prereqs && make install && export PATH="$HOME/.local/bin:$PATH"
statefulmemory --version

statefulmemory, smem, and sm are the same binary — every command in this tour can be run as sm <cmd> for brevity.

Full notes: Install. Deployment modes (self-host vs StatefulMemory Cloud): Self-hosting and Cloud.

2. Wire your agent (and optional git hooks)

Section titled “2. Wire your agent (and optional git hooks)”
Terminal window
statefulmemory install                 # MCP + skills; verify hooks if cwd is a repo
statefulmemory install --no-git-hooks  # skip hooks

Details: Wire into your agent.

3. Save an observation

Section titled “3. Save an observation”
Terminal window
statefulmemory obs save \
  --type decision \
  --title "use pgx not GORM" \
  --content "Team prefers raw SQL via pgx" \
  --session "$(uuidgen)"

Guide: Observations.

4. Search and pull context

Section titled “4. Search and pull context”
Terminal window
statefulmemory obs search "pgx"
statefulmemory obs context --query "deploy" --limit 20
statefulmemory obs context --query "deploy" --max-tokens 500

Guide: Search and context.

5. Anchor important claims

Section titled “5. Anchor important claims”
Terminal window
statefulmemory obs save \
  --type decision \
  --title "login uses JWT" \
  --content "Accept only HS256 in production" \
  --anchor src/auth.rs::login \
  --session "$(uuidgen)"


statefulmemory verify

Guide: Anchors and verify.

6. Decide when notes conflict

Section titled “6. Decide when notes conflict”
Terminal window
statefulmemory decide "Should we keep SQLite or move to Postgres?"

Needs an agent CLI (STATEFULMEMORY_LLM_*) or Laya. Guide: Decide.

7. Turn on Laya System-1

Section titled “7. Turn on Laya System-1”
Terminal window
smem doctor                    # prints laya enabled / url / health
curl -s http://127.0.0.1:8765/health
# { "ok": true, "backend": "mlx", "loaded": [...], "error": null }

smem install already wired the sidecar — native laya-mlx on Apple Silicon (~13 ms router P50), PyTorch elsewhere. Decide and conflict take the fast path; weak calls fall back to your agent CLI. Guide: Laya System-1.

8. Back up

Section titled “8. Back up”
Terminal window
statefulmemory mem export --out backup.mem

Guide: Mem archives.

Data lives under ~/.statefulmemory/. The daemon auto-starts on first use.

Next

Section titled “Next”