Troubleshooting

Run the doctor first

npx memctl doctor

This checks credentials, connectivity, org/project access, and memory capacity in one command. Fix any failing checks before investigating further.

Common errors

Token not found

Token not present

The CLI could not find an API token. Fix:

1. Run npx memctl auth to save your token, or
2. Set MEMCTL_TOKEN in your MCP config env block, or
3. Check that ~/.memctl/config.json exists and has a valid profiles.default.token

Token invalid

Token invalid

The token was found but rejected by the API. Fix:

1. Go to Settings > API Tokens in the dashboard
2. Generate a new token
3. Run npx memctl auth again with the new token

Org or project not accessible

Org not accessible
Project not accessible

The token is valid but doesn't have access to the specified org or project. Fix:

1. Check that MEMCTL_ORG and MEMCTL_PROJECT match the slugs in your dashboard URL
2. Verify you are a member of the organization
3. Slugs are case-sensitive and use lowercase with hyphens

API not reachable

API not reachable

Cannot connect to the mem/ctl API. Fix:

1. Check your network connection
2. If self-hosting, verify your API URL is correct (MEMCTL_API_URL)
3. Check if a firewall or proxy is blocking outbound HTTPS
4. The CLI will fall back to offline mode automatically

Memory capacity full

Memory capacity full. Delete unused memories before storing new ones.

Your project has reached its plan limit. Fix:

1. Run npx memctl capacity to see current usage
2. Use npx memctl list --sort updated to find old memories
3. Delete unused memories: npx memctl cleanup
4. Archive instead of delete if you want to keep data: use the memory.archive action
5. Upgrade your plan for higher limits

Rate limit exceeded

Rate limit exceeded

Too many write operations in a single session. The default limit is 500 writes per session.

1. Wait for the current session to end and start a new one
2. Set a higher limit with MEMCTL_RATE_LIMIT=1000 in your MCP config env
3. Use memory_advanced.batch_mutate instead of individual writes for bulk operations

MCP connection issues

Agent says "MCP server not found" or "tool not available"

1. Verify the MCP config file is in the correct location for your agent (see Agent Setup)
2. Make sure npx is available in your PATH
3. Restart your IDE after editing MCP config files
4. Check that Node.js 20+ is installed: node --version

Agent connects but tools fail

1. Run npx memctl doctor to check credentials
2. Check that MEMCTL_ORG and MEMCTL_PROJECT are set in the MCP config env block
3. Look at your IDE's MCP server logs for error details

Slow first response

On first startup, the MCP server syncs memories from the API. This can take a few seconds depending on how many memories you have. Subsequent tool calls use the local cache and are fast.

Config issues

Wrong org/project being used

The CLI resolves config in this order:

1. Environment variables (MEMCTL_TOKEN, MEMCTL_ORG, MEMCTL_PROJECT)
2. Project config from ~/.memctl/config.json matched by working directory
3. Default profile token + env org/project

Check each level:

# See what the CLI resolves
npx memctl doctor

# Check config file
cat ~/.memctl/config.json

Config file corrupted

Delete and recreate:

rm ~/.memctl/config.json
npx memctl auth

Local cache issues

If you suspect stale data from the local cache:

rm ~/.memctl/cache.db

The cache is rebuilt automatically on the next MCP server startup.

Data issues

Memories not syncing between team members

1. Verify both team members are using the same org and project slugs
2. Memory is stored server-side and available within 30 seconds (cache TTL)
3. Have the other team member run context.bootstrap to pull fresh data
4. Check that memories are scoped to project not stored with a different scope

Stale context after changes

If your agent has stale data mid-session:

• Use context.bootstrap_delta with a timestamp to get only recent changes
• Or use context.bootstrap to reload everything fresh
• The in-memory cache has a 30-second TTL, so waiting briefly also works

Pending writes not replayed

If writes were queued offline and not replayed:

1. Check ~/.memctl/pending-writes.json exists and has content
2. Ensure the API is now reachable: npx memctl doctor
3. Start a new MCP server session - it replays pending writes on startup

Still stuck?

• Check the Concepts page for how sync and caching work
• Run npx memctl doctor and share the output
• Open an issue at github.com/memctl/memctl