Metadata-Version: 2.4
Name: engram-dev
Version: 0.2.0
Summary: Local, persistent memory for AI development workflows
Home-page: https://github.com/Tobbiloba/engram
Author: Project Engram
Project-URL: Bug Reports, https://github.com/Tobbiloba/engram/issues
Project-URL: Source, https://github.com/Tobbiloba/engram
Keywords: ai memory rag vector-database mcp claude cursor codebase
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain>=0.1.0
Requires-Dist: langchain-community>=0.0.10
Requires-Dist: langchain-huggingface>=0.0.1
Requires-Dist: langchain-text-splitters>=0.0.1
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: transformers<5.0.0,>=4.41.0
Requires-Dist: huggingface-hub<1.0.0,>=0.23.0
Requires-Dist: torch>=2.0.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: pypdf>=3.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: ocr
Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
Requires-Dist: pdf2image>=1.16.0; extra == "ocr"
Requires-Dist: Pillow>=9.0.0; extra == "ocr"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Engram

**Local, persistent memory for AI development workflows.**

Your AI assistant finally remembers your entire codebase.

---

## The Problem

- Cursor forgets your codebase after 5 minutes
- Claude loses context mid-conversation
- Copilot suggests code that conflicts with your architecture
- You keep re-explaining the same things

## The Solution

Engram creates a **persistent memory layer** that any AI can access via MCP.

```bash
# Index your project
engram init ~/my-project

# Configure Claude/Cursor
engram setup

# Done. Your AI now remembers everything.
```

---

## Features

- **Local-first** — Your code never leaves your machine
- **GPU accelerated** — Fast indexing with MPS (Mac) or CUDA
- **MCP native** — Works with Claude Desktop, Cursor, and any MCP client
- **Incremental updates** — Only re-indexes what changed
- **Crash-proof** — Saves progress, resumes if interrupted
- **Portable** — Copy your "memory cartridge" anywhere

### Supported Files

| Type | Extensions |
|------|------------|
| Code | `.py` `.js` `.ts` `.tsx` `.go` `.rs` `.java` `.rb` `.php` `.swift` `.c` `.cpp` |
| Docs | `.pdf` `.txt` `.md` `.rst` |
| Config | `.json` `.yaml` `.yml` `.toml` |
| Images | `.png` `.jpg` `.jpeg` (OCR) |

---

## Quick Start

### Install

```bash
pip install engram-dev
```

Or from source:
```bash
git clone https://github.com/Tobbiloba/engram.git
cd engram
pip install -e .
```

### Index Your Project

```bash
# Index current folder
engram init

# Index specific folder
engram init ~/projects/my-app

# Custom output name
engram init ~/projects/my-app -o my_brain
```

### Configure MCP

```bash
engram setup
```

This auto-detects Claude Desktop and Cursor, and configures them.

### Query From Terminal

```bash
engram query "how does authentication work"
```

### Watch for Changes

```bash
engram watch ~/projects/my-app
```

Runs in background, auto-updates index when files change.

---

## How It Works

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Files     │────▶│   Chunks    │────▶│  Vectors    │────▶│   FAISS     │
│  Code/Docs  │     │ 1000 chars  │     │ 384 dims    │     │   Index     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
                                                                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│     AI      │◀────│   Results   │◀────│  Semantic   │◀────│ MCP Server  │
│   Claude    │     │  Top 5      │     │   Search    │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
```

1. **Index** — Engram scans your files and creates chunks
2. **Embed** — Each chunk becomes a 384-dimension vector (local model, no API)
3. **Store** — Vectors saved to FAISS index (fast similarity search)
4. **Query** — MCP server exposes `query_memory` tool to AI assistants
5. **Search** — AI asks questions, gets relevant code/docs back

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `engram init [folder]` | Index a folder |
| `engram query "..."` | Search from terminal |
| `engram watch [folder]` | Start background watcher |
| `engram status` | Show index stats |
| `engram setup` | Auto-configure MCP |

---

## Manual MCP Configuration

If `engram setup` doesn't work, add manually:

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "engram": {
      "command": "/path/to/engram/venv/bin/python",
      "args": ["/path/to/engram/server.py", "/path/to/your_engram"]
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "engram": {
      "command": "/path/to/engram/venv/bin/python",
      "args": ["/path/to/engram/server.py", "/path/to/your_engram"]
    }
  }
}
```

---

## Requirements

- Python 3.9+
- ~2GB disk space (for model + index)
- For OCR: `brew install tesseract poppler`

---

## Tech Stack

- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2 (runs locally)
- **Vector Store**: FAISS
- **GPU**: MPS (Apple Silicon) / CUDA (NVIDIA) / CPU fallback
- **Protocol**: MCP (Model Context Protocol)

---

## Roadmap

- [x] Local vector indexing
- [x] MCP server
- [x] GPU acceleration
- [x] Incremental updates
- [x] Background watcher
- [x] Temporal memory (what changed recently?)
- [x] Git-aware context
- [ ] Architecture insights
- [ ] Desktop app

See [ROADMAP.md](ROADMAP.md) for details.

---

## Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT — Use freely, modify freely, share freely.

---

**Built for developers who are tired of re-explaining their codebase.**
