readme

Author: Ashish-dwi99

README.md

@@ -16,7 +16,7 @@
 </p>
 
 <p align="center">
-  <a href="https://pypi.org/project/engram"><img src="https://img.shields.io/badge/python-3.9%2B-blue.svg" alt="Python 3.9+"></a>
+  <a href="https://pypi.org/project/engram-memory"><img src="https://img.shields.io/badge/python-3.9%2B-blue.svg" alt="Python 3.9+"></a>
   <a href="https://github.com/Ashish-dwi99/Engram/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
   <a href="https://github.com/Ashish-dwi99/Engram/actions"><img src="https://github.com/Ashish-dwi99/Engram/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
   <a href="https://github.com/Ashish-dwi99/Engram"><img src="https://img.shields.io/github/stars/Ashish-dwi99/Engram?style=social" alt="GitHub Stars"></a>
@@ -28,6 +28,7 @@
   <a href="#%EF%B8%8F-architecture">Architecture</a> &middot;
   <a href="#-integrations">Integrations</a> &middot;
   <a href="#-api--sdk">API & SDK</a> &middot;
+  <a href="#-longmemeval-on-colab-gpu">LongMemEval</a> &middot;
   <a href="https://github.com/Ashish-dwi99/Engram/blob/main/CHANGELOG.md">Changelog</a>
 </p>
 
@@ -60,13 +61,60 @@ But unlike "store everything forever" approaches, Engram treats agents as **untr
 ## Quick Start
 
 ```bash
-pip install -e ".[all]"            # 1. Install
-export GEMINI_API_KEY="your-key"   # 2. Set one API key (or OPENAI_API_KEY, or OLLAMA_HOST)
+pip install engram-memory          # 1. Install from PyPI
+export GEMINI_API_KEY="your-key"   # 2. Set one key before starting Engram
 engram install                     # 3. Auto-configure Claude Code, Cursor, Codex
 ```
 
 Restart your agent. Done — it now has persistent memory across sessions.
 
+### PyPI Install Options
+
+```bash
+# Default runtime (Gemini + local Qdrant + MemoryClient deps)
+pip install engram-memory
+
+# Full stack extras (MCP server + REST API + async + all providers)
+pip install "engram-memory[all]"
+
+# OpenAI provider add-on
+pip install "engram-memory[openai]"
+
+# Ollama provider add-on
+pip install "engram-memory[ollama]"
+```
+
+### API Key: When and How to Provide It
+
+Engram reads provider credentials when a process initializes `Memory()` (for example: `engram`, `engram-api`, `engram-mcp`, or your Python app).
+
+1. Set env vars **before** starting those processes.
+2. If you change keys, restart the process.
+3. Default provider is Gemini, so set `GEMINI_API_KEY` or `GOOGLE_API_KEY` unless you override provider config.
+
+```bash
+# Default (Gemini)
+export GEMINI_API_KEY="your-key"
+engram-api
+```
+
+```bash
+# OpenAI provider
+export OPENAI_API_KEY="your-key"
+engram-api
+```
+
+```bash
+# Ollama (local; no cloud key)
+export OLLAMA_HOST="http://localhost:11434"
+engram-api
+```
+
+For remote usage via `MemoryClient`, provider API keys are needed on the **server** running Engram.  
+The client only needs:
+- `ENGRAM_ADMIN_KEY` (or `admin_key=...`) when minting sessions via `/v1/sessions`
+- Bearer session token for normal read/write API calls
+
 **Or with Docker:**
 
 ```bash
@@ -565,6 +613,70 @@ Biological inspirations: Ebbinghaus Forgetting Curve → exponential decay, Spac
 
 ---
 
+## LongMemEval on Colab (GPU)
+
+Use this flow to benchmark Engram on LongMemEval in Google Colab with GPU acceleration.
+
+```bash
+# 1) In Colab: Runtime -> Change runtime type -> GPU
+
+# 2) Install Engram + GPU reader dependencies
+pip install -U engram-memory transformers accelerate
+
+# 3) Download LongMemEval data
+mkdir -p /content/longmemeval
+cd /content/longmemeval
+curl -L -o longmemeval_s_cleaned.json \
+  https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json
+
+# 4) Run Engram benchmark (HF reader on GPU)
+python -m engram.benchmarks.longmemeval \
+  --dataset-path /content/longmemeval/longmemeval_s_cleaned.json \
+  --output-jsonl /content/longmemeval/engram_hypotheses.jsonl \
+  --retrieval-jsonl /content/longmemeval/engram_retrieval.jsonl \
+  --answer-backend hf \
+  --hf-model Qwen/Qwen2.5-1.5B-Instruct \
+  --embedder-provider simple \
+  --llm-provider mock \
+  --vector-store-provider memory \
+  --history-db-path /content/engram-longmemeval.db \
+  --top-k 8 \
+  --max-questions 100 \
+  --skip-abstention
+```
+
+Notes:
+- The output file is evaluator-compatible (`question_id`, `hypothesis` per line).
+- `--include-debug-fields` adds retrieval diagnostics into each output row.
+- The command above uses `simple` embedder + `mock` LLM for memory operations, so **no Gemini/OpenAI key is required**.
+
+If you want to run with Gemini only (no extra reader packages), use base install and set key **before** starting the run:
+
+```bash
+pip install -U engram-memory
+export GEMINI_API_KEY="your-key"
+
+python -m engram.benchmarks.longmemeval \
+  --dataset-path /content/longmemeval/longmemeval_s_cleaned.json \
+  --output-jsonl /content/longmemeval/engram_hypotheses.jsonl \
+  --answer-backend engram-llm \
+  --llm-provider gemini \
+  --embedder-provider gemini \
+  --vector-store-provider memory
+```
+
+Optional official QA scoring from the LongMemEval repo:
+
+```bash
+cd /content
+git clone https://github.com/xiaowu0162/LongMemEval.git
+cd /content/LongMemEval/src/evaluation
+export OPENAI_API_KEY="your-key"
+python evaluate_qa.py gpt-4o /content/longmemeval/engram_hypotheses.jsonl /content/longmemeval/longmemeval_s_cleaned.json
+```
+
+---
+
 ## Docker
 
 ```bash

pyproject.toml

@@ -26,6 +26,9 @@ classifiers = [
 
 dependencies = [
     "pydantic>=2.0",
+    "google-generativeai>=0.3.0",
+    "qdrant-client>=1.7.0",
+    "requests>=2.28.0",
 ]
 
 [project.optional-dependencies]
@@ -41,11 +44,8 @@ api = [
     "uvicorn[standard]>=0.27.0",
 ]
 all = [
-    "google-generativeai>=0.3.0",
     "openai>=1.0.0",
     "ollama>=0.4.0",
-    "qdrant-client>=1.7.0",
-    "requests>=2.28.0",
     "mcp>=1.0.0",
     "fastapi>=0.109.0",
     "uvicorn[standard]>=0.27.0",
@@ -67,6 +67,7 @@ engram = "engram.main_cli:main"
 engram-mcp = "engram.mcp_server:run"
 engram-install = "engram.cli:install"
 engram-api = "engram.api.server:run"
+engram-longmemeval = "engram.benchmarks.longmemeval:main"
 
 [project.urls]
 Homepage = "https://github.com/Ashish-dwi99/Engram"