ailang-inbox

name	ailang-inbox
description	Cross-agent communication system with semantic search and GitHub sync. Check messages, find similar content, deduplicate, and sync with GitHub Issues for AI workflows across sessions.

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