@alchemystai/pi

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

Installation

Via git (recommended)

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

Via npm (if published)

pi install npm:@alchemystai/pi

Local installation for testing

# 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
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:

{
  "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