AILANG Inbox

AILANG's messaging system enables AI agents to communicate asynchronously across sessions and projects. Features semantic search (SimHash + Ollama neural), deduplication, and GitHub sync.

Session Start Routine

At the start of EVERY session, check for messages:

# Check for unread messages
ailang messages list --unread

# Or check specific inbox
ailang messages list --inbox user --unread

Quick Reference

Command	Purpose
`ailang messages list --unread`	Check for new messages
`ailang messages list --inbox user`	Check user inbox
`ailang messages send user "msg" --from agent`	Send to user
`ailang messages ack MSG_ID`	Mark as read
`ailang messages ack --all`	Mark all as read
`ailang messages read MSG_ID`	View full message
`ailang messages reply MSG_ID "text"`	Reply to GitHub issue thread
`ailang messages forward MSG_ID --to inbox`	Forward to another inbox
`ailang messages triage`	Cluster unread messages by intent
`ailang messages search "query"`	Semantic search (SimHash)
`ailang messages search "query" --neural`	Neural search (Ollama)
`ailang messages search --space code "path"`	Search specific envelope slot
`ailang messages dedupe`	Find duplicate messages
`ailang messages dedupe --apply`	Mark duplicates

Checking Messages

List Messages

# All messages
ailang messages list

# Only unread
ailang messages list --unread

# Specific inbox
ailang messages list --inbox user

# Filter by sender
ailang messages list --from sprint-executor

# Limit results
ailang messages list --limit 5

# JSON output (for parsing)
ailang messages list --json

Read Full Message

# View complete message content
ailang messages read MSG_ID

Acknowledge Messages

# Mark single message as read
ailang messages ack MSG_ID

# Mark all unread as read
ailang messages ack --all

# Mark all in specific inbox
ailang messages ack --all --inbox user

# Mark as unread again (for retry)
ailang messages unack MSG_ID

Sending Messages

To User

# Simple text message
ailang messages send user "Task completed successfully" --from my-agent --title "Status Update"

# With JSON payload
ailang messages send user --json '{"status":"done","result":"All tests passing"}' --from my-agent

To Another Agent

# Send to specific agent inbox
ailang messages send sprint-executor "Ready for handoff" --from planner

# With correlation ID (for tracking workflows)
ailang messages send sprint-executor --json '{"task":"execute"}' --from planner --correlation workflow_123

Workflow Patterns

1. Session Start Check

# 1. Check for messages
ailang messages list --unread

# 2. If messages exist:
#    - Summarize to user
#    - Ask what action to take

# 3. After handling:
ailang messages ack --all

2. Agent Handoff

# Agent A completes work and hands off to Agent B
ailang messages send agent-b --json '{
  "type": "handoff",
  "task": "continue_implementation",
  "artifacts": ["path/to/results/"],
  "context": "Previous work completed"
}' --from agent-a --correlation project_xyz

3. Completion Notification

# Notify user that autonomous work is done
ailang messages send user --json '{
  "type": "completion",
  "status": "success",
  "summary": "All 5 milestones completed",
  "artifacts": ["results/v1.0/"]
}' --from sprint-executor --title "Sprint Complete"

4. Error Reporting

# Report error to user
ailang messages send user --json '{
  "type": "error",
  "error": "Tests failing at milestone 3",
  "details": "logs/error.log",
  "needs_help": true
}' --from executor --title "Error Encountered"

Correlation IDs

Track related messages across agent handoffs:

{
  "message_id": "msg_20251208_103045_abc123",
  "correlation_id": "workflow_project_x",
  "from": "planner",
  "to": "executor",
  "payload": { ... }
}

Benefits:

Track entire workflow chains
Filter messages by workflow
Debug multi-agent interactions
Resume work from where you left off

Message Types

Completion

{
  "type": "completion",
  "status": "success",
  "result": "All tests passing",
  "artifacts": ["path/to/output/"]
}

Handoff

{
  "type": "handoff",
  "task": "next_phase",
  "context": "Previous work summary",
  "dependencies": ["file1.ail", "file2.ail"]
}

Error

{
  "type": "error",
  "error": "Description of failure",
  "details": "path/to/logs",
  "needs_help": true
}

Request

{
  "type": "request",
  "action": "review_code",
  "files": ["src/module.ail"],
  "priority": "high"
}

Triage (v0.10.0+)

Cluster unread messages by similarity to understand what's in your inbox at a glance:

# Cluster by intent (default) — "what are people asking about?"
ailang messages triage

# Cluster by code region — "which files are affected?"
ailang messages triage --cluster-by code

# Cluster by context — "what were senders working on?"
ailang messages triage --cluster-by context

# Show top 5 clusters only
ailang messages triage --top 5

# JSON output for programmatic use
ailang messages triage --json

Reply and Forward

# Reply to a GitHub issue thread associated with a message
ailang messages reply MSG_ID "Fixed in v0.10.0" --from claude-code

# Forward a message to another inbox
ailang messages forward MSG_ID --to sprint-executor
ailang messages forward MSG_ID --to coordinator --reason "Label changed"

Semantic Envelope (v0.8.1+)

Messages carry multi-aspect embedding vectors — 5 named slots searchable independently:

Slot	Set by	Meaning
`intent`	Auto (title + payload)	What is being asked?
`code`	`--envelope-code <files>`	Which code is affected?
`context`	`--envelope-context <desc>`	What was the sender working on?
`skill`	Builder API	What expertise is needed?
`resolution`	Auto on completion	How was this resolved?

# Send with code envelope
ailang messages send executor "Fix bug" --envelope-code internal/types/unify.go
ailang messages send executor "Fix bug" --envelope-code "src/a.ail,src/b.ail"

# Auto-detect from git modified files
ailang messages send executor "Fix bug"   # --envelope-code defaults to git changes

# Skip envelope entirely
ailang messages send executor "Fix bug" --no-envelope

# Add context envelope
ailang messages send executor "Fix bug" --envelope-context "reviewing AST switches"

# Search a specific slot
ailang messages search --space code "internal/types"
ailang messages search --space intent "fix crash"
ailang messages search --space resolution "parser"

Requires an embeddings provider in ~/.ailang/config.yaml (ollama, openai, or gemini).

Package Coordination Messages

Packages use structured inbox addressing:

Address	Meaning
`pkg:vendor/name`	Package inbox
`workspace:name`	Workspace inbox
`team:name`	Team inbox

# Send to a package inbox
ailang messages send pkg:sunholo/auth "New version available"

# Notify dependents of an upgrade (creates typed envelope)
ailang pkg notify-upgrade sunholo/auth@0.2.0

# List workspaces depending on a package
ailang pkg affected-by sunholo/auth

Typed envelopes used by publish/install workflows: upgrade-available, interface-change-notice, effect-widening-warning, compatibility-report, contract-regression, migration-request, deprecation-notice, upgrade-complete, blocked, superseded

Watch for Messages

Monitor for new messages in real-time:

# Watch all inboxes
ailang messages watch

# Watch specific inbox
ailang messages watch --inbox user

Cleanup

Remove old messages:

# Remove messages older than 7 days
ailang messages cleanup --older-than 7d

# Remove expired messages
ailang messages cleanup --expired

# Preview without deleting
ailang messages cleanup --dry-run

Semantic Search (v0.5.11+)

Find messages by meaning, not just exact text. AILANG uses SimHash by default for fast, zero-cost semantic search.

Search Commands

# Search by semantic content (SimHash - default, fast)
ailang messages search "parser error handling"

# Set similarity threshold (0.0-1.0)
ailang messages search "bugs" --threshold 0.5

# Find messages similar to a specific message
ailang messages list --similar-to MSG_ID

# Hide duplicate messages (collapsed view)
ailang messages list --collapsed

# Show duplicates of a specific message
ailang messages list --duplicates-of MSG_ID

Search Flags

Flag	Default	Description
`--threshold`	0.70	Minimum similarity (0.0-1.0)
`--limit`	20	Maximum results
`--max-scan`	1000	Maximum messages to scan
`--inbox`	(all)	Filter by inbox
`--neural`	false	Use Ollama embeddings
`--simhash`	true	Force SimHash mode
`--json`	false	Output as JSON

How SimHash Works

SimHash generates a 64-bit fingerprint based on word frequencies:

Score 1.0: Identical or near-identical
Score 0.9+: Very similar (likely duplicates)
Score 0.7-0.9: Related topics
Score below 0.7: Different content

Deduplication

Find and mark duplicate messages to reduce inbox noise.

# Report duplicates (dry run - shows what would be marked)
ailang messages dedupe

# Custom similarity threshold
ailang messages dedupe --threshold 0.90

# Actually mark duplicates
ailang messages dedupe --apply

# Filter by inbox
ailang messages dedupe --inbox user --apply

How Deduplication Works

Find groups: Messages with similarity ≥ threshold are grouped
Select representative: Oldest message in each group is kept
Mark duplicates: Newer messages get dup_of set to representative's ID
View behavior: --collapsed hides messages with dup_of set

Neural Search (Ollama)

For more sophisticated semantic search, use neural embeddings via local Ollama.

Prerequisites

Install Ollama: https://ollama.ai
Start Ollama server: ollama serve
Pull an embedding model: ollama pull nomic-embed-text

Configuration

Create ~/.ailang/config.yaml:

embeddings:
  provider: ollama
  ollama:
    model: nomic-embed-text
    endpoint: http://localhost:11434
    timeout: 30s
  search:
    default_mode: simhash
    simhash_threshold: 0.70
    neural_threshold: 0.75

Using Neural Search

# Use neural embeddings (requires Ollama running)
ailang messages search "parser bugs" --neural

# Force SimHash (faster, no Ollama needed)
ailang messages search "parser bugs" --simhash

Model Recommendations

Model	Speed	Quality	Notes
`nomic-embed-text`	Fast	Good	Best balance
`mxbai-embed-large`	Medium	Better	Higher quality
`embeddinggemma`	Fast	Good	Google model

GitHub Integration (v0.5.9+)

Sync messages with GitHub Issues for visibility across AILANG instances.

Sending to GitHub

# Bug report (creates GitHub issue)
ailang messages send user "Parser crash" --type bug --github

# Feature request
ailang messages send user "Add async support" --type feature --github

# Custom repo
ailang messages send user "Bug report" --github --repo owner/repo

Importing from GitHub

# Import issues from configured repo
ailang messages import-github

# Filter by labels
ailang messages import-github --labels bug,feature

# Preview without importing
ailang messages import-github --dry-run

GitHub Configuration

Add to ~/.ailang/config.yaml:

github:
  expected_user: YourGitHubUsername   # Must match gh auth status
  default_repo: owner/repo             # Target repo for issues
  create_labels:
    - ailang-message
  watch_labels:
    - ailang-message
  auto_import: true                    # Import on session start

Storage — two stores, and the default is the private one

Store	Selected by	Who sees it
Canonical (prod Firestore, `ailang-multivac`)	`AILANG_MESSAGES_STORE=gcp` + `AILANG_MESSAGES_PROJECT=ailang-multivac`	AILANG core and every other machine
Local SQLite (`~/.ailang/state/collaboration.db`)	default	only this machine

A message sent to the local store is not queued — it is invisible. Reports from several projects sat unread in private local databases for months because this was the default.

Add these to your shell profile so ailang messages reaches AILANG core:

export AILANG_MESSAGES_STORE=gcp
export AILANG_MESSAGES_PROJECT=ailang-multivac

Safe to export: they are scoped to messaging, so local eval and ailang chains are untouched (ailang storage status should still say Mode: local).

Verify before trusting a send. A non-local listing names its store in the header:

  store: gcp (Firestore, project ailang-multivac)

No store: line means local. If the vars ARE set and the line is still missing, your ailang predates v0.34.0 and ignores them silently — control with an invalid value, which a current binary must refuse:

AILANG_MESSAGES_STORE=not-a-real-store ailang messages list --unread
# current: errors "unknown message store mode"   old: lists normally

Shared with: Collaboration Hub dashboard
Message statuses: unread, read, archived, deleted

Integration with Collaboration Hub

Messages are visible in the web dashboard:

# Start the Collaboration Hub server
ailang serve

# Access at http://localhost:1957

The dashboard provides:

Real-time message view
Agent activity timeline
Workflow visualization
Message filtering and search

Docs: https://ailang.sunholo.com/docs/guides/agent-integration