# @alchemystai/pi

Pi extension for AlchemystAI Context Layer — persistent, retrievable memory for coding sessions.

## Installation

### Via git (recommended)

```bash
pi install git:github.com/AlchemystAI/pi-alchemyst
```

### Via npm (if published)

```bash
pi install npm:@alchemystai/pi
```

### Local installation for testing

```bash
# Clone the repository
git clone https://github.com/AlchemystAI/pi-alchemyst ~/.pi/agent/extensions/pi-alchemyst
```

## Setup

1. Get your API key from [AlchemystAI Platform](https://platform.getalchemystai.com)
2. Configure the extension in Pi:

```
Use the alchemyst_configure tool to set your API key:
- apiKey: "your-jwt-token-here"
- defaultScope: "internal" or "external" (optional)
- groupName: ["project-name"] (optional, for categorizing context)
```

This saves your configuration to `~/.config/pi-alchemyst/config.json`. It persists across sessions — you only need to do this once.

You can also pre-configure by creating the file manually:

```json
{
  "apiKey": "your-jwt-bearer-token",
  "groupName": ["pi", "my-project"]
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `alchemyst_context_search` | Search stored context for decisions, docs, and reference material |
| `alchemyst_context_add` | Save context to Alchemyst for future retrieval |
| `alchemyst_context_ask` | Ask questions grounded in your stored context |
| `alchemyst_memory_add` | Persist conversation turns to Alchemyst memory |
| `alchemyst_memory_update` | Update saved memory entries |
| `alchemyst_configure` | Configure the Alchemyst API key and settings |

## Context Arithmetic Best Practices

Alchemyst uses context arithmetic to filter and rank context. Use hierarchical groupName tags:

```
Layer 1: Domain (e.g., "engineering", "docs")
Layer 2: Project/Categories (e.g., "api-v2", "auth")
Layer 3: Specifics (e.g., "decisions", "patterns")
```

Example: `groupName: ["engineering", "backend", "auth"]`

## Features

- **Persistent Memory**: Save important decisions and recall them later
- **Context Search**: Find relevant docs across all your projects
- **Hierarchical Tagging**: Use groupName tags for precise context filtering
- **Session Memory**: Persist conversation history across sessions
- **Security Guards**: Automatically blocks secrets and sensitive data

## Environment Variables

- `ALCHEMYST_API_KEY`: Your Alchemyst API JWT token
- `ALCHEMYST_BASE_URL`: Override API endpoint (optional)
- `ALCHEMYST_DEFAULT_SCOPE`: "internal" or "external" (optional)
- `ALCHEMYST_GROUP_NAME`: Comma-separated tags (optional)

Environment variables take priority over saved values — useful for per-session overrides.

## License

MIT