---
name: alchemyst-context
description: Use AlchemystAI's Context Layer for persistent, retrievable memory across coding sessions. Search for prior decisions, save important context, and recall conversations.
---

# Alchemyst Context Layer for Pi

This skill enables Pi to use AlchemystAI's Context Layer for persistent memory and context retrieval across coding sessions.

## Setup

1. Get your API key from 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"
- baseUrl: (optional, defaults to https://platform-backend.getalchemystai.com)
- defaultScope: "internal" or "external" (optional)
- groupName: ["project-name"] (optional, for categorizing context)
```

## Available Tools

### alchemyst_context_search
Search stored context for relevant documents, decisions, and reference material.

**When to use:**
- Before answering questions about prior team decisions
- When looking for documented specs or conventions
- To find relevant code patterns or architecture decisions

**Parameters:**
- `query`: Natural language search query
- `scope`: "internal" (project-only) or "external" (org-wide)
- `similarity_threshold`: Max similarity (0-1, default 0.8)
- `minimum_similarity_threshold`: Min similarity (0-1, default 0.5)
- `mode`: "fast" or "standard" search mode

### alchemyst_context_add
Save decisions, facts, or reference snippets for future sessions.

**When to use:**
- After making important architectural decisions
- When documenting configuration choices
- To save code snippets or patterns worth remembering
- Store API keys, endpoints, or setup instructions (as "resource")
- Store coding conventions or preferences (as "instruction")

**Parameters:**
- `content`: The document content to save
- `context_type`: "resource" for reference material, "instruction" for conventions
- `scope`: "internal" or "external"
- `groupName`: Optional tags for categorization
- `source`: Optional source identifier

### alchemyst_context_ask
Ask a question and get a synthesized answer grounded in your stored context.

**When to use:**
- Quick factual lookups
- When you want a summarized answer instead of raw search results
- For questions like "What was our decision on X?" or "How does Y work?"

**Parameters:**
- `query`: Natural language question
- `steeringPrompt`: Optional instruction to steer answer format
- `scope`, `similarity_threshold`, `minimum_similarity_threshold`: Same as search

### alchemyst_memory_add
Persist conversation turns from this session to Alchemyst memory.

**When to use:**
- To save important conversation history
- Before ending a session you want to resume later
- To maintain context across Pi restarts

### alchemyst_memory_update
Update previously saved memory entries.

**When to use:**
- To correct or amend saved conversation turns
- When context changes during a session

## 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"]`

## Environment Variables

- `ALCHEMYST_API_KEY` or `ALCHEMYST_BASE_URL`
- `ALCHEMYST_DEFAULT_SCOPE` ("internal" or "external")
- `ALCHEMYST_GROUP_NAME` (comma-separated tags)

## Platform Limits

- Max file size: 50MB
- Max batch size: 100 documents per add() call
- Supported file types: .pdf, .txt, .docx, .md, .json, .csv
- Rate limit: 1000 requests/minute (default)

## Troubleshooting

- **401/403 errors**: Check your API key
- **402 errors**: Account billing restriction
- **429 errors**: Rate limit exceeded, wait and retry
- **409 errors**: Document with same `fileName` exists - delete first or use versioned filename