CLI Reference
Complete reference for the af command-line tool.
Installation
curl -sL https://dev.alwaysforever.ai/af > /usr/local/bin/af && chmod +x /usr/local/bin/af
af help
Requirements: bash, curl, python3 (for JSON formatting). No other dependencies.
Setup
af init <api-key>
Save your API key locally. The key is stored at ~/.alwaysforever with 600 permissions (owner-only read/write).
af init af_live_hiWlflSDD3LpOlJv9wC4QJbCxCQHXb2dYPvMj6fZrZg
✓ API key saved to /home/user/.alwaysforever
✓ Key verified — you're connected to AlwaysForever.ai
Alternative: Set the AF_API_KEY environment variable instead of running af init.
export AF_API_KEY=af_live_YOUR_KEY
Memory Commands
af store <content>
Store a memory. Memories are automatically enriched with semantic tags and embeddings.
| Flag | Default | Description |
|---|
--type | stm | Memory type: stm, conversation, or event |
--stm-type | insight | STM category (see table below) |
--importance | 0.5 | Importance score from 0.0 to 1.0 |
STM types:
| Type | Use for | Example |
|---|
decision | Strategic choices | "Switched to PostgreSQL for persistence" |
work | Code changes, fixes | "Fixed auth middleware timeout bug" |
insight | Realizations, patterns | "User asks about deployment every Monday" |
lesson | Things learned | "Always validate JWT before parsing claims" |
checkpoint | Milestones | "v2.0 API migration complete" |
bug | Issues found | "Race condition in session cleanup" |
error | Errors encountered | "ModuleNotFoundError: redis" |
af store "User prefers dark mode"
af store "Migrated from REST to GraphQL" --stm-type decision --importance 0.9
af store "How do I reset my password?" --type conversation
af store "Deployment to staging complete" --type event
af recall <query>
Semantic search across all your memories. Returns the most relevant results.
| Flag | Default | Description |
|---|
--limit | 10 | Maximum number of results (1-200) |
--hours | all time | Only search within last N hours |
af recall "user preferences"
af recall "deployment issues" --hours 24
af recall "architecture decisions" --limit 50
af recent [limit]
Get the most recent memories, sorted by time. Useful for session continuity.
af recent
af recent 5
Platform Commands
af sessions
List all sessions for your account.
af sessions
af health
Check platform health status. This endpoint is public (no API key required).
af health
af whoami
Verify your connection and show account info.
af whoami
Environment Variables
| Variable | Description |
|---|
AF_API_KEY | API key (alternative to af init) |
AF_BASE_URL | Override base URL (default: https://dev.alwaysforever.ai) |
AF_CONFIG | Override config file path (default: ~/.alwaysforever) |
Integration Examples
Python
import httpx
client = httpx.Client(
base_url="https://dev.alwaysforever.ai",
headers={"Authorization": f"Bearer {api_key}"}
)
client.post("/v1/memory/store", json={
"type": "stm",
"content": "User prefers concise responses",
"stm_type": "insight",
"importance": 0.8
})
result = client.post("/v1/memory/recall", json={
"query": "user preferences",
"limit": 10
})
memories = result.json()
JavaScript / Node.js
const AF_KEY = process.env.AF_API_KEY;
const BASE = "https://dev.alwaysforever.ai";
await fetch(`${BASE}/v1/memory/store`, {
method: "POST",
headers: {
"Authorization": `Bearer ${AF_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
type: "stm",
content: "User prefers dark mode",
stm_type: "insight"
})
});
const res = await fetch(`${BASE}/v1/memory/recall`, {
method: "POST",
headers: {
"Authorization": `Bearer ${AF_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ query: "user preferences", limit: 10 })
});
const memories = await res.json();