diff --git a/skills/synapse-layer/README.md b/skills/synapse-layer/README.md new file mode 100644 index 0000000..e0c0932 --- /dev/null +++ b/skills/synapse-layer/README.md @@ -0,0 +1,155 @@ +# Synapse Layer Skill for Hermes Agent + +## Overview + +This skill integrates [Synapse Layer](https://synapselayer.org) — a zero-knowledge, encrypted, cross-session memory system — into Hermes Agent. All memories are encrypted with AES-256-GCM, pass through a 4-layer Cognitive Security Pipeline (PII redaction, differential privacy, intent validation, neural handover), and are retrievable from any channel (Telegram, WhatsApp, CLI, Discord). + +## Credits + +**Rafa Martins** +Website: [ramelseg.com.br](https://ramelseg.com.br) +Email: rafacpti@gmail.com +Phone/WhatsApp: +55 27 99908-2624 + +## What It Does + +- **Persistent Memory**: Context survives between sessions. You don't repeat yourself. +- **Cross-Channel**: Telegram, WhatsApp, CLI, and Discord all share the same memory pool. +- **Trust Quotient (TQ)**: Every memory gets a confidence score (0.0–1.0) so the agent knows what to trust. +- **Zero-Knowledge Encryption**: Memories are encrypted before leaving the agent. The server never sees plaintext. +- **PII Auto-Redaction**: Emails, phone numbers, API keys, IPs are automatically stripped before storage. +- **Differential Privacy**: Noise is injected into embeddings to prevent inference attacks. + +## Quick Start + +### 1. Get a Token + +Sign up at [forge.synapselayer.org](https://forge.synapselayer.org) and generate an `sk_connect_` token. + +### 2. Configure Hermes + +Add to `~/.hermes/config.yaml`: +```yaml +mcp_servers: + synapse-layer: + url: "https://forge.synapselayer.org/mcp" + headers: + Authorization: "Bearer ${SYNAPSE_TOKEN}" + timeout: 120 + connect_timeout: 60 +``` + +Add to `~/.hermes/.env`: +``` +SYNAPSE_TOKEN=sk_connect_your_token_here +``` + +### 3. Restart Hermes +```bash +hermes restart +``` + +## Available Tools + +| Tool | When to Use | +|------|-------------| +| `mcp_synapse_layer_recall` | **Every session start** — loads relevant context before responding | +| `mcp_synapse_layer_save_to_synapse` | After decisions, facts, preferences — immediate persist | +| `mcp_synapse_layer_search` | Cross-agent full-text search across all memories | +| `mcp_synapse_layer_process_text` | Auto-detect milestones/decisions in free-form text | +| `mcp_synapse_layer_health_check` | Verify connection and system status | + +## Usage Examples + +### Session Start (Automatic Recall) +``` +mcp_synapse_layer_recall(query="current projects user preferences", agent_id="hermes-rafa") +``` + +### Save a Decision +``` +mcp_synapse_layer_save_to_synapse( + content="User prefers responses in pt-BR with Thalita voice", + agent_id="hermes-rafa", + type="[MANUAL]", + importance=5, + tags=["preference", "voice"] +) +``` + +### Search Across All Memories +``` +mcp_synapse_layer_search(query="dashboard git projects", agent_id="hermes-rafa") +``` + +### Process Free-Form Text +``` +mcp_synapse_layer_process_text( + text="We chose Synapse Layer for memory. Endpoint is forge.synapselayer.org.", + agent_id="hermes-rafa" +) +``` + +## Security Pipeline + +Every memory passes through **4 non-bypassable layers**: + +1. **Semantic Privacy Guard** — Regex-based PII/secret redaction (emails, SSNs, CPFs, credit cards, API keys, IPs) +2. **Differential Privacy** — Gaussian noise injection on embeddings (ε,δ)-DP +3. **Intent Validation** — Classifies into 8 categories (PREFERENCE, FACT, PROCEDURAL, BIO, EPHEMERAL, CRITICAL, UNKNOWN, INVALID) +4. **Neural Handover** — Conflict resolution and self-healing on recall + +## Trust Quotient Guide + +| TQ Range | Confidence | Action | +|----------|-----------|--------| +| 0.8–1.0 | High | Use directly | +| 0.5–0.8 | Medium | Verify before relying | +| 0.0–0.5 | Low | Ignore or ask user | + +## Architecture + +``` +User Input → PII Redaction → Differential Privacy → Intent Validation → Encryption → Storage + ↓ +Recall ← Decryption ← Self-Healing ← Intent Re-validation ← ← ← ← ← ← ← ← ← ← +``` + +## Known Issues + +### MCP Reconnect Loop + +If gateway logs show: +``` +Unknown SSE event: endpoint +GET stream disconnected, reconnecting in 1000ms +``` + +This is a known compatibility issue between Hermes's MCP client library and Synapse Layer's server. The **REST API works perfectly** as a fallback. The skill includes automatic fallback logic. + +### Direct REST API (Always Works) + +```bash +curl -X POST "https://forge.synapselayer.org/mcp" \ + -H "Authorization: Bearer ${SYNAPSE_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recall","arguments":{"query":"your query","limit":3}}}' +``` + +## Files + +- `SKILL.md` — Full skill documentation with setup, usage, and troubleshooting +- `README.md` — This file (English overview) + +## Links + +- **Website**: https://synapselayer.org +- **Forge Dashboard**: https://forge.synapselayer.org/forge +- **GitHub**: https://github.com/SynapseLayer/synapse-layer +- **Docs**: https://synapselayer.org/docs + +## Version History + +- **0.3.0** (17/04/2026) — Fixed endpoint URL (/mcp not /api/mcp), added credits, improved README +- **0.2.0** — MCP client reconnect loop workaround documented +- **0.1.0** — Initial integration diff --git a/skills/synapse-layer/SKILL.md b/skills/synapse-layer/SKILL.md new file mode 100644 index 0000000..8c0d3c6 --- /dev/null +++ b/skills/synapse-layer/SKILL.md @@ -0,0 +1,283 @@ +--- +name: synapse-layer +version: 0.3.0 +description: Zero-Knowledge persistent memory layer for Hermes Agent. Provides encrypted cross-session memory, Trust Quotient (TQ) scoring, and automatic recall across ALL channels (Telegram, WhatsApp, CLI, Discord). +homepage: https://synapselayer.org +credits: Rafa Martins | rafacpti@gmail.com | | ramelseg.com.br +metadata: {"synapse":{"category":"memory","requires":{"env":["SYNAPSE_TOKEN"]},"mcp":{"type":"http","url":"https://forge.synapselayer.org/mcp","auth":"Bearer ${SYNAPSE_TOKEN}"}}} +--- + +# Synapse Layer — Persistent Memory for Hermes + +**Credits**: Rafa Martins (rafacpti@gmail.com | | ramelseg.com.br) +**Website**: [synapselayer.org](https://synapselayer.org) | **Forge**: [forge.synapselayer.org/forge](https://synapselayer.org/forge) | **GitHub**: [github.com/SynapseLayer/synapse-layer](https://github.com/SynapseLayer/synapse-layer) + +Zero-Knowledge encrypted memory that persists across ALL Hermes channels. Context survives between sessions, Telegram/WhatsApp/CLI all share the same memory. + +--- + +## Setup + +### 1. Add MCP Server to config.yaml + +Add to `~/.hermes/config.yaml` at the root level (same indentation as `display:`, `mcp_servers:`): + +```yaml +mcp_servers: + synapse-layer: + url: "https://forge.synapselayer.org/mcp" + headers: + Authorization: "Bearer ${SYNAPSE_TOKEN}" + timeout: 120 + connect_timeout: 60 +``` + +### 2. Add Token to .env + +Add your Synapse Layer token to `~/.hermes/.env`: + +``` +SYNAPSE_TOKEN=sk_connect_your_token_here +``` + +Get your token at: https://synapselayer.org/forge + +### 3. Disable Tool Progress for Telegram (IMPORTANT) + +The `tool_progress` feature shows tool names in Telegram when the model uses MCP tools. To prevent `mcp_synapse_layer_search` from appearing as a message in Telegram, add per-platform display config: + +```yaml +display: + tool_progress_command: false + tool_progress_overrides: {} + tool_preview_length: 0 + tool_progress: all + platforms: + telegram: + tool_progress: off +``` + +### 4. Restart Hermes + +```bash +hermes restart +``` + +--- + +## Available Tools + +| Tool | Purpose | +|------|---------| +| `mcp_synapse_layer_recall` | Retrieve memories before responding (use at EVERY session start) | +| `mcp_synapse_layer_save_to_synapse` | Persist facts, preferences, decisions immediately | +| `mcp_synapse_layer_search` | Full-text cross-agent search across all memories | +| `mcp_synapse_layer_process_text` | Auto-detect milestones/decisions in free-form text | +| `mcp_synapse_layer_health_check` | Verify connection and system status | + +--- + +## Critical Usage Patterns + +### AT THE START OF EVERY NEW CONVERSATION + +Always call `recall` before generating any response. This is the #1 rule for memory to work: + +``` +mcp_synapse_layer_recall(query="contexto atual projetos usuario", agent_id="hermes-rafa") +``` + +This loads relevant memories automatically and saves tokens by avoiding reprocessing context. + +### AFTER ANY SIGNIFICANT DECISION OR FACT + +``` +mcp_synapse_layer_save_to_synapse( + content="User Rafa Martins preference: always respond in pt-BR with voice Thalita", + agent_id="hermes-rafa", + type="[MANUAL]", + importance=5, + tags=["preference", "user-profile"] +) +``` + +### WHEN USER REFERENCES SOMETHING FROM BEFORE + +``` +mcp_synapse_layer_search(query="dashboard git projetos", agent_id="hermes-rafa") +``` + +### ON FREE-FORM TEXT (auto-detect what to save) + +``` +mcp_synapse_layer_process_text( + text="We decided to use Synapse Layer for memory. API endpoint is forge.synapselayer.org. Token stored in .env.", + agent_id="hermes-rafa" +) +``` + +--- + +## Trust Quotient (TQ) + +Results from `recall` include a `tq` score (0.0 to 1.0). When multiple results match: +- **TQ > 0.8**: High confidence — use directly +- **TQ 0.5-0.8**: Medium confidence — verify before relying +- **TQ < 0.5**: Low confidence — ignore or ask user + +--- + +## Memory Categories — What Hermes Must Always Remember + +All project-related memories MUST be stored in Synapse Layer. Below is the canonical list of memory categories the agent must maintain: + +### 1. USER PROFILE +- Full name, role, company (Rafa Martins — Analista de Tecnologia na Ramel Tecnologia) +- Communication style (pt-BR, feminine, cheerful, relaxed, cautious) +- Voice preference (Edge-TTS Thalita, pt-BR) +- Website: ramelseg.com.br +- **Save when**: User shares preferences, corrections, or personal details + +### 2. USER PROJECTS (PRIORITY) +Every active project the user works on must be stored with: +- Project name and purpose +- Tech stack and key files +- Current status (active, paused, completed) +- Last interaction date +- Important decisions made +- Blockers or open questions +- **Save when**: Project mentioned, decision made, status changes + +### 3. SERVER INFRASTRUCTURE +- Server name/hostname ($server) +- Running services and ports (Open WebUI:$port, Hermes API:$port, Voice Call:$port) +- API endpoints and access credentials +- Docker containers and their configs +- **Save when**: New service added, config changed, credentials updated + +### 4. API CREDENTIALS & TOKENS +- Nous Portal token (expires ~15min, renew with `hermes auth list`) +- Synapse Layer token (sk-conxxxxxxxxxxxxxx) +- Naga.ac TTS API key +- Telegram bot token +- Aster MCP endpoint +- **Save when**: New credential added, token renewed, endpoint changed + +### 5. MEL-IA CONFIGURATION +- Model in use (MiniMax-M2.7 via Nous Portal, renamed to "Mel-IA") +- API server port ($port) +- Open WebUI port (#port) with Docker (ghcr.io/open-webui/open-webui:main) +- Voice: Edge-TTS Thalita +- **Save when**: Config changes, new model added, port changed + +### 6. VOICE CALL SYSTEM +- Location: /root/.hermes/voice_call/ +- Stack: Telethon + faster-whisper + Edge-TTS (Thalita) + aiohttp WebSocket HTTPS :8765 +- Modes: --mode msg, --mode call +- Note: PyTgCalls only works for group voice chats, NOT private calls +- **Save when**: System modified, new mode added, dependency changed + +### 7. ACTIVE SKILLS & TOOLS +- List of installed skills and their purposes +- How to invoke each skill +- Skill location (/root/.hermes/skills/) +- **Save when**: New skill installed, skill updated, skill removed + +### 8. PENDING TASKS & FOLLOW-UPS +- Active TODOs and their status +- Blocked tasks and what's blocking them +- Scheduled jobs (cron) +- **Save when**: Task created, task completed, task blocked + +### 9. DECISIONS & CONVENTIONS +- Architectural decisions (why a tool/approach was chosen) +- Coding conventions the user prefers +- Commands that should not be run without approval +- **Save when**: User makes a decision, user sets a convention + +### 10. ERROR PATTERNS & FIXES +- Known bugs and their workarounds +- Common errors and solutions +- **Save when**: Bug encountered and resolved + +--- + +## Security + +- **AES-256-GCM** encryption at rest +- **15+ PII patterns** auto-redacted (emails, phones, API keys, IPs) +- **Zero-knowledge** — no plaintext leaves the agent +- **Differential privacy** on embeddings + +Safe to store: user preferences, project decisions, environment facts, code patterns, tool quirks. + +--- + +## Architecture + +Synapse Layer pipeline on every save: +1. **PII Redaction** — removes emails, phones, API keys, IPs +2. **Intent Validation** — ensures content is appropriate +3. **Deduplication** — prevents storing duplicate memories +4. **Differential Privacy** — adds noise to embeddings +5. **AES-256-GCM Encryption** — encrypted at rest +6. **Storage** — distributed encrypted storage + +--- + +## Testing + +```bash +# JSONRPC 2.0 format — list available tools +curl -X POST "https://forge.synapselayer.org/mcp" \ + -H "Authorization: Bearer ${SYNAPSE_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' + +# Recall memories +curl -X POST "https://forge.synapselayer.org/mcp" \ + -H "Authorization: Bearer ${SYNAPSE_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"recall","arguments":{"query":"your query","limit":3}}}' +``` + +Expected: Returns tools list with recall, save_to_synapse, search, process_text, health_check. + +--- + +## Known Issues + +### MCP Client Reconnect Loop + +**Symptom**: Gateway logs show repeated `Unknown SSE event: endpoint` and `GET stream disconnected, reconnecting in 1000ms` every ~1 second. + +**Cause**: Hermes uses an older MCP client library that doesn't handle the `endpoint` SSE event type that Synapse Layer's server sends during the MCP handshake. + +**Impact**: MCP tools may not work reliably through the native MCP protocol. Direct REST API calls work perfectly. + +**Workaround**: If MCP tools fail, fall back to direct REST API calls via curl (format below). This is what the model should do automatically when MCP recall fails. + +### Direct REST API (Fallback when MCP fails) + +When MCP is unstable, call Synapse Layer tools via REST: + +```bash +# JSONRPC 2.0 format required +curl -X POST "https://forge.synapselayer.org/mcp" \ + -H "Authorization: Bearer ${SYNAPSE_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recall","arguments":{"query":"your query","limit":3}}}' +``` + +**Available methods**: `tools/call` (for recall, save_to_synapse, search, process_text, health_check), `tools/list` + +--- + +## Dashboard + +View and manage memories at: https://forge.synapselayer.org/forge + +--- + +**Created by**: Rafa Martins (ramelseg.com.br | rafacpti@gmail.com | 5527999082624) +**Last integrated**: 17/04/2026 on server rafa131 (Hermes with Nous Portal, Telegram bot: hermes-rafa_bot)