Skip to content

FAQ.md

Latest commit

 

History

History
244 lines (172 loc) · 6.18 KB

FAQ.md

File metadata and controls

244 lines (172 loc) · 6.18 KB

Frequently Asked Questions

Privacy & Security

Does RAM send my code or transcripts anywhere?

No. RAM is 100% local and offline. All data stays on your machine:

  • Transcripts are read from ~/.claude/projects/ (already on your machine)
  • Embeddings are computed locally using ONNX (no API calls)
  • Vector database is stored locally in ~/.config/ram/
  • No telemetry, no phone-home, no cloud sync

The only network activity is:

  • Downloading the embedding model on first run (~80 MB, one-time)
  • Optional: If you configure an LLM endpoint for augmentation (disabled by default)
  • Optional: If you configure OpenTelemetry export (disabled by default)

Is my data encrypted?

RAM stores data in plaintext on disk (same as Claude Code transcripts). If you need encryption, use full-disk encryption (FileVault on macOS, LUKS on Linux).

Performance

Will RAM slow down Claude Code?

No. RAM runs as a separate process and doesn't block Claude Code:

  • Indexing happens in the background (file watcher)
  • Session-start context injection takes < 500ms (after first run)
  • MCP tool calls are async and don't block the UI
  • Embedding model stays resident in memory (no reload per query)

How much disk space does RAM use?

  • Embedding model: ~80 MB (one-time download)
  • Vector index: ~10-50 MB per 10,000 chunks (depends on compression)
  • SQLite state DB: < 1 MB
  • Example: 100 Claude Code sessions → ~500 MB total

How much memory (RAM) does it use?

  • Embedding model: ~256 MB resident
  • LanceDB: reads pages on demand (not all in memory)
  • Typical usage: 300-400 MB total

Cost

Is RAM free?

Yes. RAM is open source (Apache-2.0) and free to use. No subscriptions, no API costs, no hidden fees.

Are there any API costs?

No. The default configuration uses local embeddings (fastembed) with no API calls. Optional features that could incur costs:

  • If you configure a paid LLM endpoint for augmentation (optional)
  • If you configure a paid embedding API (optional)

Compatibility

Will RAM work with my existing Claude Code setup?

Yes. RAM is additive — it doesn't modify Claude Code's behavior:

  • Transcripts are read-only (RAM never modifies them)
  • MCP server is optional (you can use CLI only)
  • Hooks are optional (you can index manually)

Can I use RAM with multiple Claude Code projects?

Yes. RAM indexes all projects in ~/.claude/projects/ automatically. Memories are scoped per-project by default, but you can search across projects or use global scope for cross-project knowledge.

Data Management

What if I delete a transcript file?

RAM's index becomes stale (points to non-existent file). Run:

ram index --rebuild

This re-scans all transcripts and rebuilds the index from scratch.

Can I sync RAM across multiple machines?

Not yet. RAM is designed for single-machine use. Syncing the database across machines could cause corruption. Planned for v0.3:

  • Export/import to portable format
  • Cloud sync via encrypted backup

Can my team share a RAM instance?

Not yet. RAM is single-user. Multi-user support requires:

  • Access control (who can see what)
  • Conflict resolution (concurrent writes)
  • Network protocol (not just local files)

This is out of scope for v0.1 but may be added in future versions.

Troubleshooting

How do I know if RAM is working?

Run these checks:

# 1. Check index status
ram status

# 2. Search for something you know exists
ram search "your recent work"

# 3. Check MCP server is running
ps aux | grep "ram serve"

# 4. Check hooks are configured
cat ~/.claude/settings.json | grep ram

If any of these fail, run:

ram doctor

RAM isn't finding my transcripts

Check transcript locations:

ram source list

Add custom locations:

ram source add /path/to/transcripts
ram index --rebuild

Session-start context isn't appearing

  1. Check hooks are configured in .claude/settings.json
  2. Check RAM is indexing: ram status
  3. Check search works: ram search "test"
  4. Restart Claude Code

The MCP server won't start

Check for lock file conflicts:

# Check if another instance is running
ps aux | grep "ram serve"

# Remove stale lock if needed
rm ~/.config/ram/ram.lock

# Try starting again
ram serve

Searches return no results

Possible causes:

  1. Index is empty: Run ram init to index existing transcripts
  2. Query is too specific: Try broader search terms
  3. Transcripts haven't been indexed yet: Check ram status

Uninstall

How do I remove RAM?

# 1. Remove binary
brew uninstall ram  # or delete binary

# 2. Remove data
rm -rf ~/.config/ram/

# 3. Remove MCP config
# Edit ~/.claude.json and remove "ramem" entry

# 4. Remove hooks
# Edit .claude/settings.json and remove "ram hook" entries

Your Claude Code transcripts are not affected (RAM never modifies them).

Advanced Usage

Can I use RAM with other AI coding tools?

RAM is designed for Claude Code but can work with any tool that:

  • Writes JSONL transcripts in a compatible format
  • Supports MCP servers
  • Can call external commands via hooks

Currently supported:

  • Claude Code (primary)
  • Zed (experimental, via transcript adapter)
  • Aider (experimental, via transcript adapter)

Can I customize the embedding model?

Yes. Edit ~/.config/ram/config.toml:

[embedding]
backend = "local_api"  # Use OpenAI-compatible API
endpoint = "http://localhost:11434/v1/embeddings"
model = "nomic-embed-text"
dimensions = 768

Can I use a different vector database?

Not currently. RAM is tightly coupled to LanceDB for:

  • Native BM25 + vector hybrid search
  • Efficient merge_insert for deduplication
  • Zero-config embedded mode

Switching to another vector DB would require significant refactoring.

How do I backup my RAM data?

# Backup the entire database
ram backup --output ~/backups/ram-$(date +%Y%m%d).tar.gz

# Restore from backup
ram restore ~/backups/ram-20260505.tar.gz

Can I export my memories to another format?

# Export to JSON
ram export --output memories.json

# Import from JSON
ram import memories.json

This is useful for:

  • Migrating to a new machine
  • Sharing specific memories with teammates
  • Archiving old project knowledge