Skip to main content

Frequently Asked Questions

General​

What is Engram?​

Engram is a semantic search system for AI conversations and documents. It allows you to ingest, search, enrich, and organize your conversation history from Claude, ChatGPT, and other sources.

What data sources are supported?​

Currently supported:

  • Claude - Export from claude.ai
  • ChatGPT - Export from chat.openai.com
  • Craft - Via MCP API

Is my data stored locally?​

Yes, all data is stored in your local PostgreSQL database. No data is sent to external services except for:

  • Embeddings (via Azure OpenAI or OpenAI)
  • Enrichment (via Azure OpenAI or OpenAI Batch API)

Setup​

What are the system requirements?​

  • Python 3.13+
  • Docker (for PostgreSQL + pgvector)
  • 4GB+ RAM recommended
  • Azure OpenAI or OpenAI API access

Do I need an API key?​

Yes, you need either:

  • Azure OpenAI API key, or
  • OpenAI API key

Both are used for embeddings and enrichment operations.

How do I export my Claude conversations?​

  1. Go to claude.ai
  2. Open Settings
  3. Navigate to "Account" or "Privacy"
  4. Click "Export Data"
  5. Download the JSON file

Usage​

How does semantic search work?​

Engram converts your documents into vector embeddings using AI models. When you search, your query is also converted to an embedding, and Engram finds the most semantically similar content using cosine distance.

What's the difference between batch and streaming enrichment?​

FeatureBatchStreaming
Cost50% cheaperStandard pricing
SpeedSlower (24hr max)Real-time
APIOpenAI Batch APIAzure OpenAI
Best forLarge operationsSmall/urgent tasks

How do clusters work?​

Engram uses HDBSCAN clustering to automatically group related documents. Clusters are then labeled using GPT-4o to generate meaningful names.

Can I undo an archive?​

Yes, use engram restore <doc_id> to restore archived documents.

Costs​

How much does it cost to run Engram?​

Costs depend on your usage:

  • Embeddings: ~$0.0001 per 1K tokens (text-embedding-3-small)
  • Enrichment: ~$0.01 per document (GPT-4o)
  • Batch enrichment: 50% cheaper

Use engram cost to track your API spending.

How can I reduce costs?​

  1. Use batch enrichment (engram enrich batch) for 50% savings
  2. Use --dry-run to preview operations
  3. Filter operations by source to process only what you need
  4. Use GPT-4o-mini for enrichment when possible

Troubleshooting​

Why is search slow?​

Common causes:

  1. Large database without proper indexes
  2. Many concurrent operations
  3. Network latency to embedding API

Solutions:

  1. Ensure pgvector indexes are created
  2. Use batch operations
  3. Consider local embedding models (future feature)

Why are my results not relevant?​

Try:

  1. Use --hybrid flag for combined semantic + keyword search
  2. Use more specific queries
  3. Check if relevant content is archived (engram view archived)

More Questions?​