# SynaBun — Complete Documentation

> Open-source vibe coding toolkit with persistent AI memory, social media automation, and 66 MCP tools for agentic coding workflows

SynaBun is an open-source agentic coding toolkit with 66 MCP tools designed for AI assistants. It combines persistent vector memory, social media automation (Twitter/X, TikTok, Facebook, Instagram, LinkedIn, WhatsApp), browser automation via Playwright, a visual whiteboard, Discord integration, and autonomous agent loops into a single MCP server. Built for vibe coding with Claude Code, Cursor, Windsurf, and any agentic IDE or MCP-compatible AI assistant. SynaBun gives AI assistants persistent memory across sessions — your AI remembers architecture decisions, bug fixes, and coding patterns instead of starting from zero.

## Architecture

SynaBun consists of five main components:

1. **MCP Server** — The core engine exposing 66 tools via the Model Context Protocol
2. **Browser Engine** — Playwright-powered Chromium with persistent sessions for web and social media automation
3. **Memory System** — SQLite vector database with semantic search and 12+ embedding providers
4. **Neural Interface** — A 3D visualization UI (Express + Three.js) for browsing and managing memories
5. **Claude Code Hooks** — Lifecycle hooks that automate memory capture and recall

### Data Flow

User/AI → MCP Tool Call → SynaBun Server → (Memory DB | Browser Engine | Whiteboard | Loop Controller)

## Social Media Automation Tools

SynaBun includes dedicated extraction tools for major social media platforms:

### Twitter/X
- **browser_extract_tweets** — Parses visible tweets into structured JSON: author, handle, text, timestamp, URL, replies, reposts, likes, views
- Navigate profiles, compose tweets, and interact via browser automation tools

### TikTok
- **browser_extract_tiktok_videos** — Extract feed videos with handle, caption, likes, comments, saves, shares, music
- **browser_extract_tiktok_search** — Parse search results with video URLs, handles, captions, views
- **browser_extract_tiktok_studio** — Extract TikTok Studio content list with titles, dates, privacy, stats
- **browser_extract_tiktok_profile** — Parse profile info and video grid with followers, following, likes

### Facebook
- **browser_extract_fb_posts** — Parse visible posts with author, text, timestamp, post URL, reactions. Works on group feeds and Pages.

### WhatsApp
- **browser_extract_wa_chats** — Parse WhatsApp sidebar chat list: name, last message, time, unread count, muted, pinned
- **browser_extract_wa_messages** — Parse messages from open chat: sender, time, direction, text

### Instagram
- **browser_extract_ig_feed** — Extract posts from Instagram feed with author, caption, likes, comments
- **browser_extract_ig_profile** — Parse profile info: bio, followers, following, posts count, profile pic
- **browser_extract_ig_reels** — Extract reels with captions, likes, comments, views, music
- **browser_extract_ig_search** — Parse Instagram search results
- **browser_extract_ig_post** — Extract individual post details with full metadata

### LinkedIn
- **browser_extract_li_feed** — Extract LinkedIn feed posts with author, content, reactions, comments
- **browser_extract_li_profile** — Parse profile info: headline, about, experience, education, skills
- **browser_extract_li_post** — Extract individual post details with reactions and comments
- **browser_extract_li_notifications** — Parse notification feed with types and timestamps
- **browser_extract_li_messages** — Extract LinkedIn messaging conversations
- **browser_extract_li_search_people** — Parse people search results with filters
- **browser_extract_li_network** — Extract network/connections data
- **browser_extract_li_jobs** — Extract job listings from search results and homepage recommendations

## Browser Automation Tools (Playwright)

Full browser control via Playwright with persistent Chromium sessions:

- **browser_navigate** — Open URLs in the AI's browser
- **browser_click** — Click elements by CSS selector, text, role, or data-testid
- **browser_fill** — Clear and fill input/textarea fields
- **browser_type** — Type text character-by-character (for contenteditable editors)
- **browser_snapshot** — Get accessible page structure as text
- **browser_screenshot** — Capture viewport as base64 JPEG
- **browser_content** — Extract full page HTML or text content
- **browser_evaluate** — Execute JavaScript in page context
- **browser_hover** — Hover over elements
- **browser_select** — Select dropdown options
- **browser_press** — Press keyboard keys
- **browser_wait** — Wait for elements, page states, or timeouts
- **browser_scroll** — Scroll page or elements
- **browser_go_back / browser_go_forward** — Browser navigation
- **browser_session** — Create, list, or close browser sessions

Each session maintains its own cookies and login state across AI conversations.

## MCP Tools (67 total)

SynaBun exposes 67 tools organized into 8 groups: Memory (9), Browser (39), Whiteboard (5), Cards (5), Discord (8), Loop (1), TicTacToe (1).

### Memory Tools (9)

#### remember
Store a new memory with content, category, importance, tags, and related files. Generates embedding vector automatically.

Parameters:
- content (required): The information to store
- category (required): Category name from the hierarchy
- importance (1-10): Default 5. 1-2=trivial, 5=normal, 8+=critical
- tags: Array of descriptive tags
- related_files: File paths this memory relates to
- project: Project scope (auto-detected from working directory)
- source: How learned (user-told, self-discovered, auto-saved)
- subcategory: Optional refinement

#### recall
Search memories by semantic similarity. Returns ranked results with similarity scores.

Parameters:
- query (required): Natural language search query
- category: Filter by category
- project: Filter by project
- tags: Filter by tags (any match)
- limit: Number of results (1-20, default 5)
- min_score: Minimum similarity threshold (0-1, default 0.3)
- min_importance: Minimum importance threshold

#### reflect
Update an existing memory's metadata or content. If content changes, the embedding vector is regenerated.

Parameters:
- memory_id (required): Full UUID of the memory
- content: Updated content
- importance: Updated importance
- category: Change category
- tags: Replace all tags
- add_tags: Add tags without replacing
- related_files: Updated file paths
- related_memory_ids: Link to related memories

#### forget
Move a memory to trash by ID. Can be restored later.

#### restore
Restore a trashed memory by ID.

#### memories
Browse recent memories or get statistics. Actions: recent, stats, by-category, by-project.

#### sync
Check for stale memories whose related files have changed since the memory was created. Compares file content hashes against stored checksums.

#### category
Manage memory categories. Actions: create, update, delete, list. Categories can be parents (top-level) or children (nested under a parent). Formats for list: flat, tree, parents-only.

#### tictactoe
Play a game of tic-tac-toe with your AI. Actions: start, move, state, end.

### Browser Tools (39)

18 general automation tools + 21 social media extraction tools, all powered by Playwright with persistent Chromium sessions.

**General automation:**
- browser_navigate — Open URLs
- browser_click — Click elements by CSS selector, text, role, or data-testid
- browser_fill — Clear and fill input fields
- browser_type — Type text character-by-character (for contenteditable editors)
- browser_snapshot — Get accessible page structure as text
- browser_screenshot — Capture viewport as base64 JPEG
- browser_content — Extract full page HTML or text
- browser_evaluate — Execute JavaScript in page context
- browser_hover — Hover over elements
- browser_select — Select dropdown options
- browser_press — Press keyboard keys and shortcuts
- browser_wait — Wait for elements, page states, or timeouts
- browser_scroll — Scroll page or elements
- browser_go_back — Navigate back
- browser_go_forward — Navigate forward
- browser_reload — Refresh the page
- browser_session — Create, list, or close browser sessions
- browser_upload — Upload files through forms

**Social media extraction:**
- browser_extract_tweets — Parse tweets: author, handle, text, timestamp, URL, replies, reposts, likes, views
- browser_extract_fb_posts — Parse Facebook posts: author, text, timestamp, URL, reactions
- browser_extract_tiktok_videos — Extract feed videos: handle, caption, likes, comments, saves, shares, music
- browser_extract_tiktok_search — Parse search results: video URLs, handles, captions, views
- browser_extract_tiktok_studio — Extract Studio content: titles, dates, privacy, stats
- browser_extract_tiktok_profile — Parse profile info: followers, following, likes, video grid
- browser_extract_wa_chats — Parse WhatsApp sidebar: name, last message, time, unread, muted, pinned
- browser_extract_wa_messages — Parse chat messages: sender, time, direction, text
- browser_extract_ig_feed — Extract Instagram feed posts: author, caption, likes, comments
- browser_extract_ig_profile — Parse Instagram profile: bio, followers, following, posts count
- browser_extract_ig_reels — Extract reels: captions, likes, comments, views, music
- browser_extract_ig_search — Parse Instagram search results
- browser_extract_ig_post — Extract individual post details with full metadata
- browser_extract_li_feed — Extract LinkedIn feed posts: author, content, reactions, comments
- browser_extract_li_profile — Parse LinkedIn profile: headline, about, experience, education, skills
- browser_extract_li_post — Extract individual post details with reactions and comments
- browser_extract_li_notifications — Parse notification feed with types and timestamps
- browser_extract_li_messages — Extract LinkedIn messaging conversations
- browser_extract_li_search_people — Parse people search results with filters
- browser_extract_li_network — Extract network/connections data
- browser_extract_li_jobs — Extract job listings from search results and homepage recommendations

### Whiteboard Tools (5)

- whiteboard_read — View whiteboard contents
- whiteboard_add — Place new items on the whiteboard
- whiteboard_update — Modify items on the whiteboard
- whiteboard_remove — Delete items from the whiteboard
- whiteboard_screenshot — Capture the whiteboard as an image

### Card Tools (5)

- card_list — See all open memory cards
- card_open — Open a memory card on screen
- card_close — Dismiss open memory cards
- card_update — Move, resize, pin, or compact cards
- card_screenshot — Capture open cards as an image

### Discord Tools (8)

- discord_guild — Manage Discord servers: list, get info, edit settings
- discord_channel — Manage channels: list, create, edit, delete, permissions
- discord_role — Manage roles: list, create, edit, delete, assign/remove
- discord_message — Send, edit, delete, pin messages; add reactions; bulk delete
- discord_member — Manage members: list, get info, kick, ban, unban, edit nickname/roles
- discord_onboarding — Manage server onboarding: get and update onboarding config
- discord_webhook — Manage webhooks: list, create, edit, delete, execute
- discord_thread — Manage threads: create, archive, unarchive, delete, list members

### Loop Tool (1)

- loop — Run, stop, or check autonomous background tasks. Actions: start, stop, status.

## Embedding Providers

SynaBun supports 12+ embedding providers:

1. OpenAI (text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002)
2. Ollama (local models like nomic-embed-text, mxbai-embed-large)
3. Voyager (voyage-3, voyage-3-lite, voyage-code-3)
4. Google Gemini (text-embedding-004)
5. Cohere (embed-english-v3.0, embed-multilingual-v3.0)
6. Mistral (mistral-embed)
7. Nomic (nomic-embed-text-v1.5)
8. Jina AI (jina-embeddings-v3)
9. Together AI
10. Fireworks AI
11. Azure OpenAI
12. AWS Bedrock

## Claude Code Hooks

Seven lifecycle hooks for automated memory management:

1. **SessionStart** — Injects memory protocol instructions at session start, triggers automatic recall of recent context
2. **UserPromptSubmit** — Analyzes user prompts for recall triggers (questions about past work, debugging, architecture decisions) and automatically surfaces relevant memories
3. **PreCompact** — Before context compaction, indexes the session as a conversation memory for future cross-session recall
4. **Stop** — Enforces auto-remember compliance: blocks session end if significant work was done without storing memories
5. **PreToolUse (WebSearch)** — Blocks WebSearch/WebFetch when a browser session is active to prevent conflicts
6. **PostToolUse (Remember)** — Tracks file edits to ensure memories are created after meaningful code changes
7. **PostToolUse (Plan)** — Stores plan content as memories when exiting plan mode

## Neural Interface

A 3D visualization built with Three.js that renders the memory graph:

- Parent categories appear as anchor discs
- Child categories appear as tag spheres
- Individual memories appear as small nodes clustered around their category
- Connections between related memories shown as lines
- Interactive: click to inspect, drag to rearrange, search to filter
- Settings panel with graphics presets (Low, Medium, High, Ultra)

Runs as an Express server (default port 3344) serving the visualization UI.

## Category System

Hierarchical tree structure:
- Parent categories are top-level organizational branches
- Child categories nest under parents for finer granularity
- Each memory belongs to exactly one category
- Categories have: name, description, color, optional parent
- Custom logos can be uploaded for parent categories

## Installation

```bash
# Using npx
npx create-synabun@latest

# Using yarn
yarn dlx create-synabun@latest

# Using pnpm
pnpm dlx create-synabun@latest

# Using bun
bunx create-synabun@latest

# From source
git clone https://github.com/danilokhury/Synabun.git
cd synabun
npm start
```

The setup wizard guides through:
1. Embedding provider selection
2. API key configuration
3. SQLite connection setup
4. Project configuration
5. Category initialization
6. Claude Code integration
7. Neural Interface launch

## Requirements

- Node.js 22.5+ (for built-in `node:sqlite`)
- SQLite vector database (automatically created at data/memory.db)
- No API keys required — local embeddings via Transformers.js work out of the box

## Links

- Website: https://synabun.ai
- GitHub: https://github.com/danilokhury/Synabun
- License: Apache 2.0