engram-core 0.21.1

# Getting Started with Engram

A quick guide to installing Engram, connecting it to your AI tools, and turning scattered project context into a shared source of truth.

Use Engram when you need one place for meetings, decisions, transcripts, and recurring project knowledge so agents can query the same context instead of reconstructing it from chat history.

---

## Installation

### From Source (Recommended)

```bash
git clone https://github.com/aiconnai/engram.git
cd engram/engram
cargo install --path .
```

This installs two binaries: `engram-server` and `engram-cli`.

### Pre-built Binaries

Download from [GitHub Releases](https://github.com/aiconnai/engram/releases):

```bash
# macOS (Apple Silicon)
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-server-macos-arm64 -o engram-server
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-cli-macos-arm64 -o engram-cli
chmod +x engram-server engram-cli
sudo mv engram-server engram-cli /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-server-macos-x86_64 -o engram-server
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-cli-macos-x86_64 -o engram-cli
chmod +x engram-server engram-cli
sudo mv engram-server engram-cli /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-server-linux-x86_64 -o engram-server
curl -L https://github.com/aiconnai/engram/releases/latest/download/engram-cli-linux-x86_64 -o engram-cli
chmod +x engram-server engram-cli
sudo mv engram-server engram-cli /usr/local/bin/
```

### Homebrew (macOS)

```bash
brew install aiconnai/engram/engram
```

### Docker

```bash
docker run -v engram-data:/data ghcr.io/aiconnai/engram-server:latest
```

---

## Configure MCP for AI Tools

Engram speaks the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), so it integrates with Claude Code, Cursor, VS Code MCP clients (like Cline/Roo Code), and other MCP-compatible tools. That matters because MCP gives agents direct access to the organized source of truth instead of forcing them to infer it from old conversations.

### Claude Code (Example)

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "engram": {
      "command": "engram-server",
      "args": [],
      "env": {
        "ENGRAM_DB_PATH": "~/.local/share/engram/memories.db"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "engram": {
      "command": "engram-server",
      "args": [],
      "env": {
        "ENGRAM_DB_PATH": "~/.local/share/engram/memories.db"
      }
    }
  }
}
```

### Other MCP Clients

Use the same `mcpServers.engram` JSON block in your client's MCP config location.

### Verify Connection

Once configured, your AI tool will have access to the MCP tools listed in [`docs/MCP_TOOLS.md`](docs/MCP_TOOLS.md). Ask it to run `memory_stats` to verify the connection is working and to confirm it can read the shared memory layer.

---

## Create Your First Memory

### Using the CLI

```bash
# Create a simple note
engram-cli create "The API uses JWT tokens for authentication" --type note

# Create with tags
engram-cli create "Deploy to staging before production" --type decision --tags "deploy,process"

# Create in a specific workspace
engram-cli create "User auth flow uses OAuth2" --workspace my-project
```

### Using MCP (Any MCP Client)

In Claude Code, Cursor, VS Code MCP clients, or any MCP-enabled assistant, you can use prompts like:

> "Remember that our API uses JWT tokens for authentication"

> "Store this as a decision memory: deploy to staging before production"

> "Search my memories for authentication notes"

The AI will call `memory_create` automatically.

### Using the HTTP MCP Transport

```bash
# Start the HTTP server
engram-server --transport http --http-port 8080

# Create a memory
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "memory_create",
      "arguments": {
        "content": "The API uses JWT tokens for authentication",
        "type": "note",
        "tags": ["auth", "api"]
      }
    }
  }'
```

---

## Search Your Memories

Engram uses hybrid search combining BM25 keyword matching, vector similarity, and fuzzy matching in a single query.

### CLI Search

```bash
# Basic search
engram-cli search "authentication"

# Search handles typos
engram-cli search "authentcation"

# Search in a specific workspace
engram-cli search "deploy" --workspace my-project
```

### MCP Search

Ask your AI assistant:

> "Search my memories for anything about authentication"

### HTTP Search

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "memory_search",
      "arguments": {
        "query": "authentication",
        "limit": 10
      }
    }
  }'
```

---

## Organize with Workspaces

Workspaces isolate memories by project or context:

```bash
# Create memories in different workspaces
engram-cli create "Use PostgreSQL for this project" --workspace backend-api
engram-cli create "React with TypeScript" --workspace frontend-app

# List all workspaces
engram-cli workspace list

# Search within a workspace
engram-cli search "database" --workspace backend-api
```

---

## Memory Tiers

Use tiers to control memory lifetime:

- **permanent** (default): Important knowledge that persists forever
- **daily**: Scratch notes that auto-expire after 24 hours

```bash
# Permanent memory (default)
engram-cli create "Architecture: microservices with event sourcing"

# Daily memory (auto-expires)
engram-cli create "Currently debugging the auth flow" --tier daily

# Promote a daily memory to permanent before it expires
engram-cli promote 42
```

---

## Cloud Sync (Optional)

Sync your memories to S3-compatible storage (AWS S3, Cloudflare R2, MinIO):

```bash
# Configure cloud sync
export ENGRAM_STORAGE_URI=s3://my-bucket/engram/memories.db
export ENGRAM_CLOUD_ENCRYPT=true  # AES-256-GCM encryption
export AWS_PROFILE=my-profile

# Start with cloud sync
engram-server
```

This enables cross-machine synchronization with encrypted storage.

---

## Key Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ENGRAM_DB_PATH` | SQLite database path | `~/.local/share/engram/memories.db` |
| `ENGRAM_STORAGE_URI` | S3 URI for cloud sync | (local only) |
| `ENGRAM_CLOUD_ENCRYPT` | Enable AES-256 encryption | `false` |
| `ENGRAM_EMBEDDING_MODEL` | Embedding provider. Values: `tfidf` (default, no API key needed), `openai` (requires `OPENAI_API_KEY`), `local` (local ONNX model, requires `ENGRAM_ONNX_MODEL_DIR`; build with `--features onnx-embed`), `clip` (multimodal; `--features multimodal`), `ollama` (`--features ollama`), `cohere` (`--features cohere`), `voyage` (`--features voyage`) | `tfidf` |
| `ENGRAM_ONNX_MODEL_DIR` | Path to directory containing `model.onnx` and `tokenizer.json`. Required when `ENGRAM_EMBEDDING_MODEL=local`. | — |
| `OPENAI_API_KEY` | Required for OpenAI embeddings | - |

---

---

## Using the SDKs

Engram ships Python and TypeScript clients that wrap the MCP HTTP transport.

### Installation

```bash
pip install engram-client        # Python
npm install engram-client        # TypeScript / Node
```

### Python quickstart

```python
import asyncio
from engram_client import EngramClient

async def main():
    async with EngramClient(
        base_url="http://localhost:3100",
        api_key="your-api-key",
        tenant="default",
    ) as client:
        # Create a memory
        mem = await client.create(
            "Discovered that the auth bug is in middleware ordering",
            tags=["bug", "auth"],
            importance=0.8,
        )

        # Search memories
        results = await client.search("auth middleware", limit=5)
        for r in results:
            print(r["content"])

        # Find related memories
        related = await client.related(mem["id"], limit=3)

        # Create a daily note
        await client.create_daily("Debugging session: fixed auth ordering issue")

asyncio.run(main())
```

### TypeScript quickstart

```typescript
import { EngramClient } from 'engram-client';

const client = new EngramClient({
  baseUrl: 'http://localhost:3100',
  apiKey: 'your-api-key',
  tenant: 'default',
});

// Create a memory
const mem = await client.create(
  'Discovered that the auth bug is in middleware ordering',
  { tags: ['bug', 'auth'], importance: 0.8 },
);

// Search memories
const results = await client.search('auth middleware', { limit: 5 });
results.forEach(r => console.log(r.content));

// Find related memories
const related = await client.related(mem.id, { limit: 3 });

// Create a daily note
await client.createDaily('Debugging session: fixed auth ordering issue');
```

---

## Next Steps

- Read the full [README](../README.md) for feature details
- See [AGENTS.md](../AGENTS.md) for the complete MCP tool reference
- Check [SCHEMA.md](SCHEMA.md) for database schema details
- Explore the [architecture overview](../README.md#architecture) to understand how components fit together