OpenSkillIndex← back to search
claude-code

Skills synap

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/antoinesrvt/synap" ~/.claude/skills/clawdbot-skills-synap && rm -rf "$T"
manifest: skills/antoinesrvt/synap/SKILL.md
source content

Synap — OpenClaw Skill

You are connected to a Synap pod at 

{SYNAP_POD_URL}
. You have sovereign, structured, persistent memory backed by PostgreSQL, Typesense full-text search, and pgvector semantic search. Your user ID is 
{SYNAP_AGENT_USER_ID}
and your workspace is 
{SYNAP_WORKSPACE_ID}
.

You can do three things with Synap:

  1. Remember — store entities, documents, facts, and relations in a typed knowledge graph
  2. Recall — search across everything by keyword, type, or semantic similarity
  3. Relay — bring external messages (Telegram, WhatsApp, Slack) into Synap and let the Synap AI process them

Every write goes through governance — some auto-approve, others create proposals for the user to review. You never lose data. You never need to organize it.

Setup

Automatic (recommended)

SYNAP_HUB_API_KEY   = hub_xxxx
SYNAP_CONFIG_URL    = https://pod.synap.live/trpc/intelligenceRegistry.getServiceConfig

Config is auto-fetched on startup. No restart needed.

Manual

SYNAP_HUB_API_KEY    = hub_xxxx
SYNAP_POD_URL        = https://pod.synap.live
SYNAP_WORKSPACE_ID   = <uuid>
SYNAP_AGENT_USER_ID  = <uuid>

All calls: 

Authorization: Bearer {SYNAP_HUB_API_KEY}
+ 
Content-Type: application/json
.

Key must have 

hub-protocol.read
AND 
hub-protocol.write
scopes.

Data Model

Entities

Typed objects with properties and relationships. The fundamental unit of knowledge.

ProfileUse forKey Properties
note
Unstructured knowledgecontent, tags
task
Actionable work itemsstatus, priority, dueDate
project
Groupingsstatus, tags
event
Time-bound occurrencesstartDate, endDate, location
person
Individualsemail, phone
contact
Business contactsrole (extends person)
company
Organizationswebsite, industry
deal
Sales opportunitiesstage, value, closeDate
bookmark
Web referencesurl, domain
article
Published contentauthor, publishedAt

Extend profiles: a "lead" extends 

person
, a "webinar" extends 
event
. Use 
GET /api/hub/profiles
to discover types. Use 
POST /api/hub/profiles
to create new ones.

Documents

Long-form Markdown. Reports, summaries, specs, meeting notes.

Facts (Memory)

Atomic knowledge that persists across sessions. "Marc prefers email over Slack."

Relations

Typed connections between entities. Types: 

related
, 
parent
, 
child
, 
belongs-to
.

Decision Tree

SituationActionPrimitive
"Remember that Marc prefers email"
POST /api/hub/memory
Fact
"Create a task to follow up"
POST /api/hub/entities
Entity
"Write a meeting summary"
POST /api/hub/documents
Document
"Marc works at Acme Corp"Create person + company, then 
POST /api/hub/relations
Relation
"What do I know about Marc?"
GET /api/hub/search?query=Marc
Search
"Someone texted me on Telegram"
POST /api/hub/threads
+ 
POST .../messages
Relay

ALWAYS search before creating to prevent duplicates.

Governance

Auto-approved:

  • All reads and searches
  • Memory storage/recall
  • Profile and property creation

May create proposal:

  • Entity creation/updates
  • Document creation
  • Relation creation/deletion

Response format:

  • { "status": "approved" }
    — executed
  • { "status": "proposed", "proposalId": "..." }
    — queued for user approval (tell user, don't retry)
  • { "status": "denied" }
    — blocked (respect, don't retry)

API Reference

Base URL: 

{SYNAP_POD_URL}/api/hub
Auth: 
Authorization: Bearer {SYNAP_HUB_API_KEY}

Search & Read

GET /api/hub/search?userId={UID}&workspaceId={WID}&query=Marc&limit=10
GET /api/hub/entities/<id>?userId={UID}&workspaceId={WID}
GET /api/hub/users/{UID}/entities?workspaceId={WID}&type=task&limit=50
GET /api/hub/documents/<id>?userId={UID}
GET /api/hub/profiles?userId={UID}&workspaceId={WID}
GET /api/hub/relations?userId={UID}&workspaceId={WID}&entityId=<id>
GET /api/hub/users/{UID}/context?workspaceId={WID}
GET /api/hub/graph/traverse?userId={UID}&startEntityId=<id>&maxDepth=2

Memory

POST /api/hub/memory
{ "userId": "{UID}", "fact": "Marc prefers email", "confidence": 0.9 }
# embedding is optional — server handles it

GET /api/hub/memory?userId={UID}&query=Marc+preferences&limit=10

DELETE /api/hub/memory/<fact-id>?userId={UID}

Create & Update

POST /api/hub/entities
{
  "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "profileSlug": "task", "title": "Follow up with Marc",
  "properties": { "status": "todo", "priority": "high", "dueDate": "2026-04-10" },
  "reasoning": "User asked to track follow-up"
}

PATCH /api/hub/entities/<id>
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "properties": { "status": "done" }, "reasoning": "Task completed" }

POST /api/hub/documents
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "title": "Meeting Notes", "content": "# Meeting\n\n...", "reasoning": "..." }

POST /api/hub/relations
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}",
  "sourceEntityId": "<id>", "targetEntityId": "<id>", "type": "related",
  "reasoning": "Marc works at Acme Corp" }

DELETE /api/hub/relations/<id>
{ "userId": "{UID}", "agentUserId": "{UID}", "workspaceId": "{WID}" }

POST /api/hub/profiles
{ "userId": "{UID}", "workspaceId": "{WID}", "name": "Lead", "slug": "lead",
  "parentProfileId": "<uuid>", "description": "Sales lead" }

POST /api/hub/property-defs
{ "userId": "{UID}", "workspaceId": "{WID}", "profileId": "<uuid>",
  "name": "Company", "slug": "company", "valueType": "string" }

Property value types: 

string
, 
number
, 
boolean
, 
date
, 
entity_id
, 
array
, 
object
, 
secret
.

Message Relay (External Channels)

When a message arrives from Telegram, WhatsApp, Slack, or another platform:

Step 1: Create or reuse a thread:

POST /api/hub/threads
{ "userId": "{UID}", "workspaceId": "{WID}", "title": "Telegram: Alice" }

Step 2: Post the message (with 

autoRespond: true
to trigger Synap AI):

POST /api/hub/threads/<thread-id>/messages
{ "role": "user", "content": "Hey are you free today?",
  "userId": "{UID}", "autoRespond": true }

Step 3: Poll for AI response:

GET /api/hub/threads/<thread-id>/messages

Filter for 

role: "assistant"
messages after your timestamp. Poll every 3s, max 45s.

A2AI (Agent-to-Agent)

Same thread/message endpoints. Post with 

autoRespond: true
, poll for response.

GET /api/hub/threads?userId={UID}&workspaceId={WID}
POST /api/hub/threads/<id>/messages
GET /api/hub/threads/<id>/messages

Error Handling

StatusMeaningAction
200SuccessProcess normally
401Invalid API keyCheck SYNAP_HUB_API_KEY
403Insufficient scopesKey needs read + write
404Not foundEntity/document doesn't exist
429Rate limitedWait 60 seconds
500Server errorRetry once after 30s

"proposed"
and 
"denied"
in response body are NOT errors — they're governance.

Best Practices

  1. Search before creating — prevent duplicates. Most important habit.
  2. Use specific entity types — 
    person
    not 
    note
    , 
    company
    not 
    bookmark
    .
  3. Store atomic facts — preferences, decisions, context. Always auto-approved.
  4. Link entities with relations — build the graph. Use graph traversal to explore.
  5. Include reasoning — every write accepts 
    "reasoning"
    . Creates audit trail.
  6. Batch related operations — person + company + relation in sequence.
  7. Read before updating — documents replace full content, not diff.
  8. Extend profiles — "lead" extends 
    person
    , "webinar" extends 
    event
    .

Filesystem Rules

PathStatus
~/openclaw/workspace/**
Auto-approved
~/projects/**
Proposal required
~/synap-backend/**
, 
.env
BLOCKED — never accessible
/etc/**
, 
/usr/**
, 
/bin/**
BLOCKED — system paths

synap v1.0.0 — github.com/synap-core/backend/tree/main/skills/synap