Synapse Layer Skill for Hermes Agent

SKILL.md

---
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)
- Contact info (email: rafacpti@gmail.com, phone: )
- 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 (serve)
- 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_connect_xxxxxxx)
- 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 | )  
**Last integrated**: 17/04/2026 on server  (Hermes with Nous Portal, Telegram bot: )