ailang-inbox

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

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

Neural Search (Ollama)

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

Prerequisites

1. Install Ollama: https://ollama.ai
2. Start Ollama server: ollama serve
3. 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

• Database: ~/.ailang/state/collaboration.db (SQLite)
• 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