Troubleshooting First Run

Harness won’t start

Symptom: memstrata serve exits immediately or curl http://localhost:8080/health returns Connection refused.

Fix 1 — Port conflict:

# Find what's on port 8080
netstat -an | grep 8080      # Linux/macOS
netstat -an | findstr 8080   # Windows

# Use a different port
memstrata serve --port 8181

Update your MCP config to match the new port.

Fix 2 — Missing init:

memstrata init    # Run this first in your project directory
memstrata serve

Fix 3 — License error:

memstrata status

If it shows License: invalid, run memstrata login to re-authenticate.

---

MCP server not showing in AI tool

Cursor: Restart Cursor after adding the MCP config. Cursor loads MCP servers on startup, not dynamically.

Claude Code: Run /mcp in a session — if MemStrata isn’t listed, check ~/.claude/settings.json for a typo in the server entry.

Continue.dev: Check the Continue output panel (VS Code → Output → Continue) for MCP connection errors.

Any tool: Verify the harness is running first:

curl http://localhost:8080/health
# Expected: {"status":"ok","version":"5.2.x"}

---

Index is stale or empty

Symptom: Dashboard shows 0 files indexed, or context responses are empty.

cd ~/my-project
memstrata status        # Shows last indexed time
memstrata index         # Trigger a manual re-index
memstrata index --rebuild  # Full rebuild (slower, clears cache)

Common causes:

• Ran memstrata init in the wrong directory
• The project path changed (moved or renamed)
• First run on a large codebase — indexing can take several minutes

---

Savings not appearing on dashboard

Symptom: Using the AI tool, but the Money tab shows $0.

1. Confirm the harness is running and the AI tool is routing through it (check memstrata logs --tail 20 for request entries).
2. Confirm the project is indexed (memstrata status shows file count > 0).
3. For browser extension: confirm it shows “Connected” in the toolbar popup.

The first few turns may show 0 savings if the graph hasn’t warmed up. Give it 5–10 turns.

---

License server unreachable

Symptom: memstrata status shows License: grace period (N hours remaining).

MemStrata operates in grace period mode for 72 hours if memstrata.dev/lic is unreachable. Check status.memstrata.dev for outage status.

If you’re behind a corporate proxy or firewall that blocks the license server, configure the proxy:

export HTTPS_PROXY=http://proxy.company.com:8080
memstrata status

---

Windows: SmartScreen warning on installer

The MSI installer is EV-signed. If you see SmartScreen on v5.2.0+, your SmartScreen cache may be stale. Click “More info → Run anyway.” The warning should not reappear after the first run.

---

macOS: “MemStrata is damaged and can’t be opened”

The DMG is Apple-notarized. This message usually means the file was quarantined during download:

xattr -d com.apple.quarantine /Applications/MemStrata.app

---

Still stuck?

Open an issue on GitHub with the output of memstrata status and memstrata logs --tail 50.