Synapse Layer Skill for Hermes Agent

Zero-Knowledge persistent memory layer for Hermes Agent. Provides encrypted cross-session memory, Trust Quotient (TQ) scoring, and automatic recall across AL...

Security Scan

The skill's purpose (encrypted cross-session memory) is plausible, but the SKILL.md asks the agent to store and recall many sensitive secrets and references a required SYNAPSE_TOKEN that the registry metadata omitted — plus the security guarantees (zero-knowledge, PII redaction) are unverified because this is an instruction-only skill.

Purpose & Capability

Name/description match the instructions: the skill integrates a remote memory service and needs a service token to talk to forge.synapselayer.org. However, the package registry metadata lists no required env vars while the SKILL.md metadata and docs explicitly require SYNAPSE_TOKEN — an inconsistency that should be corrected.

Instruction Scope

The instructions tell the agent/operator to modify ~/.hermes/config.yaml and ~/.hermes/.env, to always call recall at session start, and to persist and search across highly sensitive material (API credentials, server hostnames, ports, configs, and a root path /root/.hermes/voice_call). They also instruct disabling Telegram tool progress to hide tool usage. These behaviors are coherent with a cross-session memory service but will cause sensitive secrets to be stored remotely; the SKILL.md asserts strong protections (zero-knowledge, PII redaction) but provides no in-repo code or verifiable proof.

Install Mechanism

Instruction-only skill with no install spec or code files — nothing is written or downloaded by an installer. That's the lowest install risk, but it also means the claimed security pipeline cannot be validated from the bundle.

Credentials

SKILL.md metadata and docs require a SYNAPSE_TOKEN (used as a Bearer header). Registry-level requirements list none — mismatch is suspicious. The skill also asks the agent to persist other long-lived credentials (Telegram bot token, Nous Portal token, TTS API keys, etc.) into remote memory. Requesting a single service token is appropriate, but recommending storage of many unrelated secrets increases risk and should be justified and guarded (short-lived tokens, explicit opt-in, encryption proofs).

Persistence & Privilege

The skill is not always-enabled and follows normal autonomous-invocation defaults. However, the instruction to 'always call recall before generating any response' combined with cross-channel memory access increases the blast radius: if the remote memory contains credentials or infra details, those may be used or exposed across channels. This is not a disallowed privilege by itself, but it elevates sensitivity and requires careful operator control.

What to consider before installing

Before installing, verify the following: (1) Correct the metadata mismatch — ask the publisher why the registry shows no required env vars while SKILL.md requires SYNAPSE_TOKEN. (2) Confirm you trust https://forge.synapselayer.org and review their privacy/security docs and source code (the skill bundle contains no code to verify their zero-knowledge/PII-redaction claims). (3) Avoid storing long-lived credentials in remote memory unless you understand and accept the risk — prefer short-lived tokens, rotate credentials after testing, and limit what the agent is allowed to persist. (4) Test with non-sensitive data first to confirm behavior and inspect network requests. (5) If you need to store secrets, ensure there is an auditable access policy and the service's encryption/zero-knowledge design is independently verifiable. (6) Ask the publisher to remove recommendations that reference root-only paths (/root/.hermes/...) and to clarify why tool-progress must be disabled for Telegram (this hides agent actions and can reduce transparency).

Synapse Layer — Persistent Memory for Hermes

Credits: Rafa Martins ([e-mail] | | ramelseg.com.br)
Website: synapselayer.org | Forge: forge.synapselayer.org/forge | GitHub: 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:):

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:

display:
  tool_progress_command: false
  tool_progress_overrides: {}
  tool_preview_length: 0
  tool_progress: all
  platforms:
    telegram:
      tool_progress: off

4. Restart Hermes

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: [e-mail], 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

# 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:

# 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 | [e-mail] | )
Last integrated: 17/04/2026 on server (Hermes with Nous Portal, Telegram bot: )