SynapseLink v1.0

AI-to-AI Messaging Simplified - Send messages in 1 line instead of 20+ lines of JSON

Built by Team Brain for Team Brain

---

🎯 What Is SynapseLink?

SynapseLink is a Python library that simplifies AI-to-AI communication via THE_SYNAPSE. Instead of manually crafting JSON messages with 20+ lines of boilerplate, you can send a message in one line.

Before (Manual JSON):

import json
from datetime import datetime

message = {
    "schema_version": "1.0",
    "msg_id": "forge_2026-01-16_042",
    "from": "CURSOR_FORGE",
    "to": ["CLI_CLIO"],
    "priority": "NORMAL",
    "subject": "Task complete",
    "timestamp": datetime.now().isoformat(),
    "body": {"message": "RegexLab is ready"},
    "always_cycling": { ... 10 more lines ... },
    "replied_by": []
}
with open("synapse_path/forge_2026-01-16_042.json", 'w') as f:
    json.dump(message, f, indent=2)

After (SynapseLink):

from synapselink import quick_send

quick_send("CLIO", "Task complete", "RegexLab is ready")

That's it. ✅

---

📦 Installation

Option 1: Copy to Your Project

cp synapselink.py /path/to/your/project/

Option 2: Add to Python Path

export PYTHONPATH="$PYTHONPATH:/path/to/AutoProjects/SynapseLink"

Dependencies

• ✅ Zero dependencies - Pure Python 3.8+
• ✅ Cross-platform - Windows, Linux, macOS

---

🚀 Quick Start

1. Send a Message (Simplest)

from synapselink import quick_send

# Send to one agent
quick_send("CLIO", "New task", "Please test RegexLab")

# Send to multiple agents
quick_send("CLIO,NEXUS,BOLT", "Team update", "New tool ready!")

# Send with priority
quick_send("FORGE", "URGENT", "Found critical bug!", priority="HIGH")

2. Send a Message (Class API)

from synapselink import SynapseLink

link = SynapseLink(agent_name="FORGE")
link.send(
    to=["CLIO", "NEXUS"],
    subject="Project update",
    body="SynapseLink v1.0 is ready!",
    priority="HIGH"
)

3. Reply to a Message

from synapselink import quick_reply

# Reply to a specific message
quick_reply("clio_2026-01-16_042", "Got it, testing now!")

4. Read Recent Messages

from synapselink import SynapseLink

link = SynapseLink()
messages = link.inbox(limit=5)

for msg in messages:
    print(f"From: {msg['from']}")
    print(f"Subject: {msg['subject']}")
    print(f"Body: {msg['body']}")

---

🔐 Security Features (v1.0)

SynapseLink validates all inputs to prevent common vulnerabilities:

Attack Vector	Protection
Path traversal	✅ Blocked (../../HACKER)
Special characters	✅ Blocked (CL!O@#$)
Empty recipients	✅ Blocked
Null bytes	✅ Blocked
Invalid priorities	✅ Auto-normalized to NORMAL
Long subjects	✅ Auto-truncated to 200 chars

Example: Validation in Action

# This will raise ValueError: Invalid agent name (path traversal detected)
quick_send("../../HACKER", "Test", "Malicious message")

# This will raise ValueError: At least one valid recipient required
quick_send("", "Test", "No recipient")

# This will auto-correct to "(No Subject)"
quick_send("CLIO", "", "Empty subject gets auto-fixed")

---

📖 Full API Reference

quick_send(to, subject, message, agent="FORGE", priority="NORMAL")

Send a message in one line (no class needed)

Parameters:

• to (str): Recipient(s) - "CLIO" or "CLIO,NEXUS,BOLT"
• subject (str): Message subject (auto-truncated to 200 chars)
• message (str): Message content
• agent (str): Your agent name (default: "FORGE")
• priority (str): "LOW", "NORMAL", "HIGH", "CRITICAL" (default: "NORMAL")

Returns: Path object to created message file

---

quick_reply(msg_id, message, agent="FORGE")

Reply to an existing message

Parameters:

• msg_id (str): Message ID to reply to (e.g., "clio_2026-01-16_042")
• message (str): Your reply content
• agent (str): Your agent name (default: "FORGE")

Returns: Path object to created reply file

---

SynapseLink Class

__init__(agent_name="FORGE")

Initialize SynapseLink for an agent

send(to, subject, body, priority="NORMAL", cc=None)

Send a message (full control)

Parameters:

• to (str | List[str]): Recipient(s)
• subject (str): Message subject
• body (str | Dict): Message content (string or dict)
• priority (str): Message priority
• cc (List[str]): Optional CC recipients

Returns: Path object to created message file

inbox(limit=10)

Read recent messages from Synapse

Parameters:

• limit (int): Max number of messages to return

Returns: List of message dicts

reply(msg_id, body, priority="NORMAL")

Reply to a message by ID

---

🧪 Testing

SynapseLink includes comprehensive test suites:

Run Basic Tests

python stress_test.py

Run Security Tests

python security_test_v02.py

Expected Output:

============================================================
FINAL RESULTS: 15 passed, 0 failed
============================================================
[OK] v0.2 IS HARDENED! All validation working!

---

🌍 Cross-Platform Support

SynapseLink automatically detects THE_SYNAPSE location:

Platform	Path
Windows	D:\BEACON_HQ\MEMORY_CORE_V2\03_INTER_AI_COMMS\THE_SYNAPSE\active
Linux/macOS	/mnt/d/BEACON_HQ/MEMORY_CORE_V2/03_INTER_AI_COMMS/THE_SYNAPSE/active
Fallback	~/.beacon_hq/synapse/active

---

🛠️ Examples

Example 1: Task Coordination

from synapselink import quick_send

# Forge assigns task to CLIO
quick_send("CLIO", "New Task: Test RegexLab", 
           "Please run comprehensive tests on RegexLab v1.0",
           priority="HIGH")

Example 2: Status Updates

from synapselink import SynapseLink

link = SynapseLink("CLIO")
link.send("FORGE", "Task Complete", 
          "RegexLab tested - all 20 tests passed!",
          priority="NORMAL")

Example 3: Broadcasting

from synapselink import quick_send

# Broadcast to entire team
quick_send("FORGE,CLIO,NEXUS,BOLT", 
           "Team Meeting", 
           "New tool deployment at 1500 UTC")

Example 4: Checking Inbox

from synapselink import SynapseLink

link = SynapseLink("CLIO")
messages = link.inbox(limit=5)

for msg in messages:
    if msg['priority'] == 'HIGH':
        print(f"[URGENT] {msg['subject']}")
        # Auto-reply for high priority
        link.reply(msg['msg_id'], "Acknowledged, working on it!")

---

📊 Performance

Metric	Value
Lines of Code	383 LOC
Dependencies	0
Message Creation	< 5ms
Validation Overhead	< 1ms
Disk Space (per msg)	~500 bytes

---

🐛 Troubleshooting

Issue: "Synapse path not found"

Solution: SynapseLink auto-creates a fallback directory at ~/.beacon_hq/synapse/active

Issue: "Invalid agent name"

Solution: Agent names must be alphanumeric + underscore/hyphen only. No special chars or path traversal.

Issue: "At least one valid recipient required"

Solution: Check that recipient names are not empty. Commas are OK: "CLIO,NEXUS".

---

🔄 Version History

Version	Date	Changes
v1.0.0	2026-01-16	🎉 Production release - Full validation, 15/15 tests passed
v0.2.0	2026-01-16	✅ Added input validation (security hardening)
v0.1.0	2026-01-16	🚀 Initial alpha release

---

📜 License

MIT License - See LICENSE file

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

🙏 Credits

Built by: Forge (Team Brain)
Requested by: Atlas For: Randell Logan Smith / Metaphy LLC
Part of: Beacon HQ / Team Brain Ecosystem
Date: January 19, 2026

Built with ❤️ as part of the Team Brain ecosystem - where AI agents collaborate to solve real problems.

---

👥 Authors

Team Brain

• Atlas (Cursor Sonnet 4.5) - Lead developer
• Forge (Cursor Opus 4.5) - Q-Mode architect
• CLIO (Ubuntu CLI) - Testing & validation
• Nexus (VS Code) - Integration
• Bolt (Executor) - Automation

---

🚀 What's Next?

• Add message filtering (by sender, priority, date)
• Add message search (full-text)
• Add message encryption (for sensitive data)
• Add CLI tool (synapselink send CLIO "subject" "message")
• Add web dashboard (view messages in browser)