Troubleshooting

Worker Issues

Worker Not Starting

Symptoms: Worker service doesn't start or crashes immediately.

Solutions:

1. Check if port is already in use:

lsof -i :7432

2. Kill existing process:

kill $(cat ~/.mem-oracle/worker.pid)

3. Start with a different port:

MEM_ORACLE_PORT=8080 bun run worker

Worker Not Responding

Symptoms: Health check fails or requests timeout.

Check health:

curl http://localhost:7432/health

View logs:

tail -f ~/.mem-oracle/worker.log

Restart worker:

# Stop
kill $(cat ~/.mem-oracle/worker.pid)

# Start
bun run worker

Indexing Issues

Indexing Stuck

Symptoms: Status shows pages stuck in "pending" state.

Solutions:

1. Check crawler logs:

tail -100 ~/.mem-oracle/worker.log | grep -i crawl

2. Verify the URL is accessible:

curl -I https://example.com/docs

3. Force re-index:

curl -X POST http://localhost:7432/refresh \
  -H "Content-Type: application/json" \
  -d '{"baseUrl": "https://example.com", "force": true}'

Pages Failing to Index

Symptoms: Many pages in "failed" status.

Common causes:

• Rate limiting by the target site
• JavaScript-rendered content
• Authentication required

Solutions:

1. Increase request delay:

{
  "crawler": {
    "requestDelay": 2000
  }
}

2. Check failed pages:

curl http://localhost:7432/status | jq '.docsets[].indexStatus.errorPages'

Content Not Extracted

Symptoms: Pages indexed but no meaningful content.

Solutions:

1. The site may use JavaScript rendering. Mem- Oracle works best with static HTML or server-rendered pages.

2. Check if the site has a sitemap or alternative documentation source.

Search Issues

No Results Found

Symptoms: Search returns empty results.

Solutions:

1. Verify documentation is indexed:

curl http://localhost:7432/status

2. Try a broader query with a higher topK:

curl -X POST http://localhost:7432/retrieve \
  -H "Content-Type: application/json" \
  -d '{"query": "getting started", "topK": 10}'

3. Check if the query matches indexed content topics.

Low Quality Results

Symptoms: Results don't match the query well.

Solutions:

1. Use a better embedding provider:

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "apiKey": "sk-..."
  }
}

2. Re-index after changing providers:

# Delete existing docset
curl -X DELETE http://localhost:7432/docset/{id}

# Re-index
curl -X POST http://localhost:7432/index ...

Plugin Issues

Claude Code Plugin Not Working

Symptoms: Documentation not being injected into prompts.

Solutions:

1. Verify plugin is installed:

/plugin list

2. Check worker is running:

curl http://localhost:7432/health

3. Reinstall plugin:

/plugin remove mem-oracle
/plugin marketplace add jagjeevanak/mem-oracle && /plugin install mem-oracle

4. Restart Claude Code.

OpenCode Plugin Not Loading

Symptoms: Plugin not recognized by OpenCode.

Solutions:

1. Verify files are in correct location:

ls -la .opencode/plugin/
ls -la .opencode/skills/
ls -la .opencode/command/

2. Check file permissions:

chmod +x .opencode/plugin/mem-oracle.ts

3. Restart OpenCode.

Storage Issues

Disk Space

Symptoms: Errors about disk space or storage.

Check usage:

du -sh ~/.mem-oracle/
du -sh ~/.mem-oracle/cache/
du -sh ~/.mem-oracle/vectors/

Clean up:

# Remove old cache files
find ~/.mem-oracle/cache -mtime +30 -delete

# Or delete a specific docset
curl -X DELETE http://localhost:7432/docset/{id}

Database Corruption

Symptoms: SQLite errors or inconsistent state.

Solutions:

1. Backup and rebuild:

cp ~/.mem-oracle/metadata.db ~/.mem-oracle/metadata.db.backup
rm ~/.mem-oracle/metadata.db
# Worker will recreate on next start

2. Re-index your documentation.

API Key Issues

OpenAI API Errors

Symptoms: Embedding fails with authentication errors.

Solutions:

1. Verify API key:

echo $OPENAI_API_KEY

2. Check config:

cat ~/.mem-oracle/config.json | jq '.embedding'

3. Test API key directly:

curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "model": "text-embedding-3-small"}'

Getting Help

If you're still having issues:

1. Check the GitHub Issues
2. Search existing issues for similar problems
3. Open a new issue with:
   • Your configuration (without API keys)
   • Relevant log output
   • Steps to reproduce