synabun 1.3.0 → 2.0.0-beta

package/README.md

@@ -1,853 +1,175 @@
-<p align="center">
-  <img src="public/synabun.png" alt="SynaBun" width="120" />
-</p>
-
-<h1 align="center">SynaBun</h1>
-
-<p align="center">
-  Persistent vector memory for AI assistants — powered by SQLite and local embeddings.
-</p>
-
-<p align="center">
-  <a href="https://discord.gg/x6yWqE9GZP"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
-  <a href="https://x.com/SynabunAI"><img src="https://img.shields.io/badge/Follow-%40SynabunAI-000000?logo=x&logoColor=white" alt="X / Twitter" /></a>
-  <img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+" />
-  <img src="https://img.shields.io/badge/MCP-Protocol-8B5CF6" alt="MCP Protocol" />
-  <img src="https://img.shields.io/badge/SQLite-Database-003B57?logo=sqlite&logoColor=white" alt="SQLite" />
-</p>
-
-<p align="center">
-  <a href="https://synabun.ai">synabun.ai</a>
-</p>
-
----
-
-Any Claude Code instance (or MCP-compatible AI tool) can connect to SynaBun and retain knowledge across sessions through semantic vector search. Memories are stored in a local SQLite database with built-in vector search — no external services, no API keys, no Docker.
-
-## Screenshots
-
-<table>
-<tr>
-<td align="center" width="50%">
-<strong>Neural Interface</strong><br><br>
-<img src="docs/screenshots/neural-interface.png" alt="3D memory graph visualization" width="100%" />
-<br><em>Interactive 3D force-directed graph — memories as nodes, relationships as edges</em>
-</td>
-<td align="center" width="50%">
-<strong>Claude Code Skin</strong><br><br>
-<img src="docs/screenshots/claude-code-skin.png" alt="Claude Code side panel skin" width="100%" />
-<br><em>Side panel UI for browsing and managing memories alongside your editor</em>
-</td>
-</tr>
-<tr>
-<td align="center" width="50%">
-<strong>Terminal & Editor</strong><br><br>
-<img src="docs/screenshots/terminal-editor.png" alt="Claude Code terminal with memory tools" width="100%" />
-<br><em>Memory tools running directly in your terminal alongside code</em>
-</td>
-<td align="center" width="50%">
-<strong>Automation Studio</strong><br><br>
-<img src="docs/screenshots/automation-studio.png" alt="Automation studio for background tasks" width="100%" />
-<br><em>Autonomous background loops — set a task and let it run</em>
-</td>
-</tr>
-</table>
-
-## Features
-
-- **Semantic Search** — find memories by meaning, not keywords, using cosine similarity
-- **Multi-Project** — single collection serves all projects with automatic project detection and cross-project recall
-- **Smart Relevance** — time decay (90-day half-life), project boost (1.2x), and access frequency scoring
-- **User-Defined Categories** — hierarchical categories with prescriptive routing descriptions; dynamic schema refresh without server restart
-- **Neural Interface** — interactive 3D force-directed graph visualization at `localhost:3344`
-- **Local Embeddings** — built-in Transformers.js (`all-MiniLM-L6-v2`, 384 dims) — no API key or internet needed after first run
-- **Onboarding Wizard** — guided setup through the Neural Interface UI
-- **Trash & Restore** — soft-delete with full restore capability; trash management via Neural Interface
-- **Memory Sync** — SHA-256 file hash tracking detects when related source files change, flagging stale memories
-- **OpenClaw Bridge** — read-only integration overlays OpenClaw workspace memories as ephemeral nodes in the 3D graph
-- **Category Logos** — upload custom logos for parent categories, rendered on sun nodes in the 3D visualization
-- **Backup & Restore** — export and import SQLite database snapshots via the Neural Interface
-- **Claude Code Hooks** — 7 lifecycle hooks automate memory recall, storage, and session indexing
-- **User Learning** — autonomous observation of user communication patterns, preferences, and behavioral singularity across sessions
-- **Claude Code `/synabun` Command** — single slash command hub with interactive menu for brainstorming, auditing, health checks, and memory search
-- **Leonardo AI Integration** — 4 browser-based MCP tools for AI image and video generation via Leonardo.ai — no API key needed, full UI automation via Playwright with the `/leonardo` skill for guided creation
-
-## Table of Contents
-
-- [Screenshots](#screenshots)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [MCP Tools](#mcp-tools)
-- [Neural Interface](#neural-interface)
-- [Usage](#usage)
-- [Memory Categories](#memory-categories)
-- [Importance Scale](#importance-scale)
-- [How It Works](#how-it-works)
-- [Configuration](#configuration)
-- [Claude Code Hooks](#claude-code-hooks)
-- [Claude Code Skills](#claude-code-skills)
-- [CLAUDE.md Integration](#claudemd-integration)
-- [Multi-Project Support](#multi-project-support)
-- [Known Limitations](#known-limitations)
-- [Troubleshooting](#troubleshooting)
-- [Cost](#cost)
-- [File Structure](#file-structure)
-- [License](#license)
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| **[Website Docs](https://synabun.ai/docs.html)** | Full documentation on synabun.ai |
-| **[README](./README.md)** | Quick start, architecture, configuration |
-| **[Usage Guide](./docs/usage-guide.md)** | Detailed usage patterns, tool quirks, best practices |
-| **[API Reference](./docs/api-reference.md)** | Neural Interface REST API (55+ endpoints) |
-| **[Hooks Guide](./docs/hooks.md)** | Claude Code hooks: 7 lifecycle hooks for memory automation |
-| **[Contributing](./CONTRIBUTING.md)** | Bug reports, feature requests, and forking guide |
-| **[Security](./SECURITY.md)** | Security model and vulnerability reporting |
-| **[Changelog](./CHANGELOG.md)** | Version history |
-
-**Contributions:** We welcome [bug reports and feature requests](https://github.com/ZaphreBR/synabun/issues). Pull requests are not accepted. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
-
-## Quick Start
-
-### Prerequisites
-
-- Node.js 22.5+ (for built-in `node:sqlite`)
-
-No Docker, no API keys, no external services required.
-
-<details>
-<summary><strong>Optional: Build tools for terminal features</strong></summary>
-
-The Neural Interface includes an embedded terminal powered by `node-pty` (native addon). If build tools are missing, `npm install` will warn but continue — everything else works fine.
-
-| Platform | Install |
-|----------|---------|
-| macOS | `xcode-select --install` |
-| Linux | `sudo apt install build-essential python3` |
-| Windows | [VS Build Tools 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++" |
-
-</details>
-
-### Install via npm
-
-```bash
-npm install -g synabun
-synabun
-```
-
-### Or clone from GitHub
-
-```bash
-git clone https://github.com/danilokhury/Synabun.git
-cd Synabun
-npm start
-```
-
-Either method will:
-1. Check prerequisites (Node.js 22.5+)
-2. Install all dependencies
-3. Build the MCP server
-4. Create the SQLite database (`data/memory.db`)
-5. Download the embedding model (~23MB, cached permanently)
-6. Launch the Neural Interface
-7. Open the onboarding wizard in your browser
-
-<details>
-<summary><strong>Manual setup (advanced)</strong></summary>
-
-### 1. Build the MCP server
-
-```bash
-cd mcp-server
-npm install
-npm run build
-```
-
-> **Note:** Always use `npm run build` (not `npx tsc`) — npx can install an unrelated `tsc` package instead of using the local TypeScript compiler.
-
-### 2. Register with your AI tool
-
-Add to your project's `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "SynaBun": {
-      "command": "node",
-      "args": ["/path/to/Synabun/mcp-server/run.mjs"]
-    }
-  }
-}
-```
-
-Or register globally for all projects:
-
-```bash
-claude mcp add SynaBun -s user \
-  -- node "/path/to/Synabun/mcp-server/run.mjs"
-```
-
-No environment variables needed — SQLite and local embeddings work out of the box.
-
-### 3. Verify
-
-Restart Claude Code, then run `/mcp`. You should see the `SynaBun` server with 72 tools listed.
-
-</details>
-
-<details>
-<summary><strong>Platform-specific path notes</strong></summary>
-
-The `.mcp.json` path must match the platform where **Claude Code is running**:
-
-| Platform | Path format | Example |
-|----------|-------------|---------|
-| **Windows** | Forward slashes | `D:/Apps/Synabun/mcp-server/run.mjs` |
-| **WSL** | Linux mount paths | `/mnt/d/Apps/Synabun/mcp-server/run.mjs` |
-| **Linux/macOS** | Native paths | `/home/user/Apps/Synabun/mcp-server/run.mjs` |
-
-**Common pitfall:** If Claude Code runs on Windows but you use a WSL-style path like `/mnt/j/...`, Node.js will resolve it to `J:\mnt\j\...` (prepending the drive letter), which doesn't exist. Always use Windows-native paths when Claude Code runs on Windows.
-
-</details>
-
-## Architecture
-
-```
-AI Assistant (any project)
-    │
-    │  MCP Protocol (stdio or HTTP)
-    │
-┌───┴──────────────────────────┐
-│   SynaBun MCP Server         │  Node.js 22.5+ / TypeScript
-│                              │
-│  72 tools across 9 groups:   │
-│  Memory (8), Browser (39),   │
-│  Whiteboard (5), Cards (5),  │
-│  Discord (8), Leonardo (4),  │
-│  Git (1), Loop (1),          │
-│  TicTacToe (1)               │
-│                              │
-│  Transformers.js             │  Local embeddings
-│  all-MiniLM-L6-v2            │  (384 dims, ~23MB model)
-│                              │
-│  node:sqlite                 │  Built-in SQLite
-│  data/memory.db              │  (vectors as Float32 BLOBs)
-│                              │
-│  Playwright                  │  Browser automation
-│  (Chromium)                  │  (persistent sessions)
-└──────────────────────────────┘
-```
-
-Everything runs in a single Node.js process — no external services, no Docker, no API keys.
-
-## MCP Tools (72)
-
-SynaBun exposes 72 tools via the Model Context Protocol, organized into 9 groups:
-
-### Memory (8 tools)
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `remember` | Store a new memory | `content`, `category`, `project`, `tags`, `importance`, `subcategory` |
-| `recall` | Semantic search across memories | `query`, `category`, `project`, `tags`, `limit`, `min_importance` |
-| `reflect` | Update an existing memory | `memory_id` (full UUID), `content`, `importance`, `tags`, `category` |
-| `forget` | Soft-delete a memory (moves to trash) | `memory_id` |
-| `restore` | Restore a trashed memory | `memory_id` |
-| `memories` | List recent memories or get stats | `action` (recent, stats, by-category, by-project) |
-| `sync` | Detect stale memories via file hash comparison | `project` (optional filter) |
-| `category` | Create, update, delete, or list categories | `action` (create, update, delete, list), `name`, `description`, `parent` |
-
-### Browser (39 tools)
-
-18 general browser automation tools + 21 social media extraction tools, all powered by Playwright with persistent Chromium sessions.
-
-**General automation:**
-`browser_navigate`, `browser_click`, `browser_fill`, `browser_type`, `browser_hover`, `browser_select`, `browser_press`, `browser_evaluate`, `browser_snapshot`, `browser_content`, `browser_screenshot`, `browser_session`, `browser_go_back`, `browser_go_forward`, `browser_reload`, `browser_wait`, `browser_scroll`, `browser_upload`
-
-**Social media extraction:**
-`browser_extract_tweets`, `browser_extract_fb_posts`, `browser_extract_tiktok_videos`, `browser_extract_tiktok_search`, `browser_extract_tiktok_studio`, `browser_extract_tiktok_profile`, `browser_extract_wa_chats`, `browser_extract_wa_messages`, `browser_extract_ig_feed`, `browser_extract_ig_profile`, `browser_extract_ig_post`, `browser_extract_ig_reels`, `browser_extract_ig_search`, `browser_extract_li_feed`, `browser_extract_li_profile`, `browser_extract_li_post`, `browser_extract_li_notifications`, `browser_extract_li_messages`, `browser_extract_li_search_people`, `browser_extract_li_network`, `browser_extract_li_jobs`
-
-### Whiteboard (5 tools)
-
-| Tool | Purpose |
-|------|---------|
-| `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 |
-
-### Cards (5 tools)
-
-| Tool | Purpose |
-|------|---------|
-| `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 (8 tools)
-
-| Tool | Purpose |
-|------|---------|
-| `discord_guild` | Server info, channels, members, roles, audit log |
-| `discord_channel` | Create, edit, delete channels and set permissions |
-| `discord_role` | Create, edit, delete roles, assign/remove from members |
-| `discord_message` | Send, edit, delete, pin, react, bulk delete, list messages |
-| `discord_member` | Member info, kick, ban, unban, timeout, nickname |
-| `discord_onboarding` | Welcome screen, rules, verification, onboarding prompts |
-| `discord_webhook` | Create, edit, delete, list, execute webhooks |
-| `discord_thread` | Create, archive, unarchive, lock, delete threads |
-
-### Automation (1 tool)
-
-| Tool | Purpose |
-|------|---------|
-| `loop` | Run, stop, or check autonomous background tasks |
-
-### Leonardo AI (4 tools)
-
-Browser-based AI image and video generation via [Leonardo.ai](https://app.leonardo.ai). No API key needed — all tools automate the Leonardo.ai web UI directly via Playwright.
-
-| Tool | Purpose |
-|------|---------|
-| `leonardo_browser_navigate` | Navigate to specific Leonardo.ai pages (home, library, image editor, video, upscaler, blueprints, realtime canvas, models) |
-| `leonardo_browser_generate` | Fill the prompt and click Generate — configure UI settings (model, style, dimensions, motion controls) beforehand using generic browser tools |
-| `leonardo_browser_library` | View or search the Leonardo.ai generation library |
-| `leonardo_browser_download` | Capture the current Leonardo.ai page as a screenshot to see generation results |
-
-> **Tip:** Use the `/leonardo` skill in Claude Code for an expert-guided creation experience with a 7-phase video prompter, 6-phase image prompter, model advisor with decision matrices for 30+ models, curated prompt library, and style guide with motion controls and camera combos.
-
-## Neural Interface
-
-SynaBun includes a 3D visualization UI for browsing and managing memories.
-
-**Start it:**
-```bash
-cd neural-interface
-npm start
-```
-
-Then open **http://localhost:3344**
-
-**What you get:**
-- Interactive force-directed graph — memories as nodes, relationships as edges
-- Click nodes to inspect, edit, or delete memories
-- Semantic search bar (press `/` to focus)
-- Category sidebar with filtering, hierarchy editing, and custom logos
-- Drag nodes to pin them in 3D space
-- Trash management — view, restore, or permanently purge deleted memories
-- Memory Sync — detect stale memories whose source files have changed (SHA-256 hash comparison)
-- Backup & Restore — export and import database snapshots
-- OpenClaw Bridge — overlay OpenClaw workspace memories as read-only ephemeral nodes
-- Graphics quality presets (Low, Medium, High, Ultra)
-- Onboarding wizard for first-time setup
-- Category export — download all memories in a category as Markdown
-
-The Neural Interface also serves as the admin panel for category management, hook installation, skill management, and MCP registration — all from a single web UI.
-
-## Usage
-
-### Storing memories
-
-Format content in **Markdown** for readability:
-
-```javascript
-remember({
-  content: `## Redis Price Cache Configuration
-
-**TTL:** 1 hour (3600 seconds)
-**Location:** \`orchestratorSingleton.ts\`
-
-**Note:** Increasing TTL improves performance but delays price updates.`,
-  category: "project",
-  importance: 7,
-  tags: ["redis", "cache", "pricing"],
-  subcategory: "architecture"
-})
-```
-
-### Searching memories
-
-```javascript
-recall({
-  query: "how does the price caching work",
-  limit: 5
-})
-```
-
-Results include similarity score, importance, age, and full content. Filter by category, project, tags, or minimum importance.
-
-### Browsing and stats
-
-```javascript
-memories({ action: "stats" })                              // Counts by category and project
-memories({ action: "recent", limit: 10 })                  // Most recent
-memories({ action: "by-category", category: "learning" })  // Filter by category
-memories({ action: "by-project", project: "myapp" })       // Filter by project
-```
-
-### Updating memories
-
-```javascript
-reflect({
-  memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2",  // Full UUID required
-  importance: 9,
-  add_tags: ["critical"]
-})
-```
-
-### Deleting and restoring memories
-
-```javascript
-// Soft-delete (moves to trash)
-forget({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })
-
-// Undo — restore from trash
-restore({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })
-```
-
-### Detecting stale memories
-
-```javascript
-// Check which memories have outdated file references
-sync({ project: "my-project" })
-// Returns: list of memories whose related_files have changed since last update
-```
-
-The `sync` tool compares SHA-256 hashes of files referenced in `related_files` against stored checksums. Use it to find memories that may need updating after code changes.
-
-For detailed usage patterns and best practices, see the [Usage Guide](./docs/usage-guide.md).
-
-## Memory Categories
-
-Categories are fully user-defined, stored per-connection in `mcp-server/data/custom-categories-{connId}.json`. There are no hardcoded defaults. Manage them via MCP tools or the [Neural Interface](#neural-interface).
-
-### How Claude Decides Where to Store Memories
-
-Category descriptions are **routing instructions** that Claude reads every time it calls `remember`. Claude reads ALL category descriptions from the tool schema and picks the best match.
-
-```
-You create categories with descriptions
-        ↓
-buildCategoryDescription() assembles them into a hierarchical guide
-        ↓
-The guide is embedded in the MCP tool schema (Zod .describe())
-        ↓
-Claude reads the guide when calling remember/recall/reflect
-        ↓
-Claude picks the category whose description best matches the memory
-```
-
-Descriptions refresh dynamically — when you change a description via MCP tools (`category_update`), the tool schemas rebuild and Claude sees the update immediately via `notifications/tools/list_changed`. No server restart needed.
-
-### Writing Effective Descriptions
-
-Descriptions should be **prescriptive rules**, not vague labels:
-
-| Quality | Example |
-|---------|---------|
-| Bad | `"Pricing and stores"` |
-| Good | `"ONLY for deal/pricing memories: store imports, price comparisons, Gamivo/YuPlay/Steam pricing. Never put project bugs here."` |
-| Bad | `"Bug fixes"` |
-| Good | `"Bug fixes, root cause analysis, error resolutions. Must be about actual code bugs — not feature requests or ideas."` |
-
-**Tips:**
-- Be explicit about boundaries — say what does NOT belong as much as what does
-- Reference other categories by name — "use deals for pricing, use bug-fixes for bugs"
-- List concrete examples — "Gamivo, YuPlay, Steam pricing data"
-- Keep it under ~200 chars — Claude reads all descriptions at once, brevity helps
-
-### Parent Categories
-
-Parent categories group related children into visual clusters. They affect how Claude sees the hierarchy:
-
-```
-[criticalpixel] (parent) — All CriticalPixel memories go here
-  bug-fixes = Bug fixes, root cause analysis, error resolutions for CP code
-  databases = Database schemas, queries, migrations, Supabase config
-deals = ONLY deal/pricing memories: store imports, price comparisons...
-memory-system = MCP server architecture, SQLite config, embedding pipeline...
-```
-
-Create parents via MCP tools:
-```javascript
-category_create({ name: "my-project", description: "All memories for my-project" })
-category_update({ name: "bug-fixes", parent: "my-project" })
-```
-
-Or via the Neural Interface sidebar — click the **Parent** button, then drag categories onto it.
-
-### Dynamic Schema Refresh
-
-```
-category_create / category_update / category_delete
-  → refreshCategorySchemas()
-    → invalidateCategoryCache()
-    → tool.update({ paramsSchema: ... })
-    → SDK sends notifications/tools/list_changed
-      → Claude re-fetches tool list → sees updated descriptions
-```
-
-## Importance Scale
-
-| Score | Meaning | When to use |
-|-------|---------|------------|
-| 1-2 | Trivial | Temporary workarounds, minor preferences |
-| 3-4 | Low | Common patterns, routine configs |
-| 5 | Normal | Standard decisions (default) |
-| 6-7 | Significant | Important patterns, non-obvious fixes |
-| 8-9 | Critical | Hard-won bug fixes, key architecture decisions |
-| 10 | Foundational | Core architecture, security rules, owner preferences |
-
-Memories with importance **8+** are immune to time-based relevance decay.
-
-## How It Works
-
-### Embedding and storage
-
-When `remember` is called, the content text is embedded locally via Transformers.js (`all-MiniLM-L6-v2`) which returns a 384-dimensional normalized vector. This vector (stored as a Float32Array BLOB), along with the payload (content, category, tags, timestamps, etc.), is inserted into the SQLite `memories` table.
-
-### Semantic search
-
-When `recall` is called, the query is embedded the same way, then cosine similarity is computed in JavaScript against all stored vectors. Results are re-ranked with:
-
-- **Time decay** — 90-day half-life (older memories score lower, unless importance >= 8)
-- **Project boost** — memories from the current project get a 1.2x score multiplier
-- **Access boost** — frequently recalled memories get a small relevance increase
-
-### SQLite schema
-
-The database stores memories, session chunks, and trash in a single `memory.db` file. Columns are indexed on `category`, `project`, `importance`, and `created_at` for fast filtered queries.
-
-### Access tracking
-
-Every time a memory is returned by `recall`, its `accessed_at` timestamp and `access_count` are updated (fire-and-forget, non-blocking).
-
-## Configuration
-
-### Environment variables
-
-SynaBun works with zero configuration by default. All settings are optional:
-
-```env
-# Optional overrides
-SQLITE_DB_PATH=/custom/path/to/memory.db   # Default: data/memory.db
-MEMORY_DATA_DIR=/custom/data/dir           # Default: mcp-server/data/
-NEURAL_PORT=3344                           # Neural Interface port (default: 3344)
-SETUP_COMPLETE=true
-
-# API keys (optional — only needed for specific integrations)
-DISCORD_BOT_TOKEN=your-token-here          # Discord server management
-```
-
-| Variable | Description |
-|----------|-------------|
-| `SQLITE_DB_PATH` | Path to SQLite database file (default: `data/memory.db`) |
-| `MEMORY_DATA_DIR` | Data directory for runtime files (default: `mcp-server/data/`) |
-| `NEURAL_PORT` | Neural Interface server port (default: 3344) |
-| `DISCORD_BOT_TOKEN` | Discord bot token for server management tools |
-
-Set these in the `.env` file at the project root, or let SynaBun use the defaults.
-
-## Embeddings
-
-SynaBun uses **local embeddings** via Transformers.js — no API key or internet connection needed (after the initial ~23MB model download).
-
-| Property | Value |
-|----------|-------|
-| **Model** | `Xenova/all-MiniLM-L6-v2` |
-| **Dimensions** | 384 |
-| **Runtime** | ONNX (via `@huggingface/transformers`) |
-| **Cache** | `~/.cache/huggingface/` (permanent, auto-downloaded on first use) |
-| **Cost** | Free |
-
-The model runs entirely in-process — no external service calls, no API keys, no network dependency after first download.
-
-## Claude Code Hooks
-
-SynaBun ships with 7 [Claude Code hooks](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/hooks) that automate memory usage across the entire coding session lifecycle.
-
-| Hook | Event | Purpose |
-|------|-------|---------|
-| `session-start.mjs` | `SessionStart` | Greeting, boot sequence, compaction recovery, loop detection, session registration |
-| `prompt-submit.mjs` | `UserPromptSubmit` | Tiered recall nudges, loop iteration injection, category tree on first threshold |
-| `pre-compact.mjs` | `PreCompact` | Captures session transcript before context compaction for conversation indexing |
-| `stop.mjs` | `Stop` | Combined obligations: compaction, loops, task memory, user learning, conversation turns, auto-store, unstored plans |
-| `post-remember.mjs` | `PostToolUse` | Tracks edit count and clears enforcement flags when memories are stored. User learning flag management |
-| `pre-websearch.mjs` | `PreToolUse` | Blocks WebSearch/WebFetch during active browser sessions to prevent interference |
-| `post-plan.mjs` | `PostToolUse` | Auto-stores plans as memories when exiting plan mode |
-
-**Install via Neural Interface:** Settings > Integrations > Enable (global or per-project).
-
-For detailed hook documentation, customization options, and custom hook templates, see the [Hooks Guide](./docs/hooks.md).
-
-## Claude Code Skills
-
-SynaBun ships [Claude Code skills](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials/custom-slash-commands) — slash commands that provide expert-guided workflows.
-
-### `/synabun` — Memory Command Hub
-
-The entry point for all memory-powered capabilities. Type `/synabun` in Claude Code and an interactive menu appears:
-
-| Option | What it does |
-|--------|-------------|
-| **Brainstorm Ideas** | Cross-pollinate memories to spark creative ideas. Uses multi-round recall with 5 query strategies (direct, adjacent, problem-space, solution-space, cross-domain) and synthesizes ideas traced back to specific memories. |
-| **Audit Memories** | Validate stored memories against the current codebase. Runs 6 phases: landscape survey, checksum pre-scan, bulk retrieval, parallel semantic verification, interactive classification (STALE/INVALID/VALID/UNVERIFIABLE), and audit report. |
-| **Memory Health** | Quick stats overview and staleness check — total count, category distribution, stale file references. |
-| **Search Memories** | Find something specific across your entire memory bank using semantic search. |
-
-### `/leonardo` — Master Media Prompter
-
-Expert-guided AI image and video creation via Leonardo.ai. Supports quick mode for power users and interactive questionnaires for guided creation.
-
-| Mode | Usage |
-|------|-------|
-| **Interactive menu** | `/leonardo` — choose between Create Video, Create Image, Quick Generate, or Account Info |
-| **Direct routing** | `/leonardo video sunset over ocean` or `/leonardo image cyberpunk portrait` |
-| **Quick mode** | `/leonardo quick a cinematic drone shot of a volcano` — skip the questionnaire, use smart defaults |
-
-The skill includes 5 expert modules: video prompter (7-phase cinematic questionnaire with motion controls and style stacking), image prompter (6-phase composition questionnaire with style presets), model advisor (decision matrices for 30+ models), prompt library (curated templates), and style guide (style stacking, motion controls, camera combos).
-
-**Install:** Copy the skills to your global skills directory:
-
-```bash
-# Skills live at:
-~/.claude/skills/synabun/SKILL.md
-~/.claude/skills/leonardo/SKILL.md
-```
-
-## CLAUDE.md Integration
-
-Add this to any project's `CLAUDE.md` to instruct Claude to use memory automatically:
-
-<details>
-<summary><strong>Show CLAUDE.md template</strong></summary>
-
-```markdown
-## Persistent Memory
-
-You have persistent vector memory via the `SynaBun` MCP server (72 tools).
-Core memory tools: remember, recall, forget, restore, reflect, memories, sync, category.
-Also available: browser automation (39 tools), whiteboard (5), cards (5), discord (8), leonardo AI (4), git, loop, tictactoe.
-
-### Auto-Recall (do this automatically)
-- At session start: recall context about the current project
-- When user mentions a specific topic: recall what you know
-- Before architecture decisions: recall past decisions
-- When debugging: recall past similar bugs
-
-### Auto-Remember (do this automatically)
-- After fixing a hard bug: remember the solution (importance 7+)
-- After architecture decisions: remember the decision and why (importance 8+)
-- When user says "remember this": importance 8+
-- API quirks or gotchas discovered: remember as learning
-- Session-ending context: remember ongoing work as conversation
-
-### Memory Tool Quirks
-- `remember` accepts `tags` and `importance` directly and returns the full UUID.
-- `forget` is a soft delete — use `restore` to undo.
-- The `reflect` tool's ID parameter is `memory_id` (not `id`). It requires the FULL UUID format.
-- Make memory MCP calls sequentially, not in parallel — one failure cascades to all sibling calls in the batch.
-```
-
-</details>
-
-## Multi-Project Support
-
-The `project` field is auto-detected from the working directory name. Memories from different projects are stored in the same collection but can be filtered independently.
-
-When `recall` is called without a project filter, it searches **all** projects but gives a 1.2x boost to results matching the current project. Cross-project knowledge (like general patterns or tool usage) is still surfaced when relevant.
-
-## Database
-
-SynaBun stores all data in a single SQLite file (`data/memory.db`). No external database service needed.
-
-```bash
-# Database location
-ls mcp-server/data/memory.db
-
-# Backup (just copy the file)
-cp mcp-server/data/memory.db ~/backups/memory-$(date +%Y%m%d).db
-```
-
-### Rebuilding after code changes
-
-```bash
-cd mcp-server
-npm run build
-```
-
-No need to restart Claude Code — the MCP server is spawned fresh on each session.
-
-### Migrating from Qdrant
-
-If you have an existing Qdrant-based installation, use the migration script:
-
-```bash
-cd mcp-server
-npm run migrate
-```
-
-This reads all memories from your Qdrant instance, re-embeds them with the local model, and inserts them into the new SQLite database.
-
-## Known Limitations
-
-### 1. `reflect` requires full UUID
-
-`remember` returns the full UUID in its output. Use it directly with `reflect`:
-
-```
-reflect({ memory_id: "8f7cab3b" })                                    // Bad Request
-reflect({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })        // Works
-```
-
-For existing memories, use `recall` to get the full UUID.
-
-### 2. Parallel tool call failures
-
-When making parallel MCP tool calls, if one fails, all sibling calls in that batch may fail. Make memory calls sequentially.
-
-## Troubleshooting
-
-<details>
-<summary><strong>Common issues and fixes</strong></summary>
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `Cannot find module '.../dist/index.js'` | TypeScript not compiled | `npm run build` inside `mcp-server/` |
-| `npx tsc` installs wrong package | npm's `tsc` package shadows TypeScript | Use `npm run build` instead |
-| Node resolves path to `J:\mnt\j\...` | WSL path used with Windows Claude Code | Use Windows paths (`J:/...`) |
-| `node:sqlite` not found | Node.js version too old | Upgrade to Node.js 22.5+ |
-| `remember` fails with type errors | Rare — older MCP SDK serialization | Update MCP SDK, or use `reflect` as fallback |
-| `reflect` returns "Bad Request" | Using shortened ID | Use full UUID from `remember` output or `recall` |
-| "Sibling tool call errored" | Parallel MCP call batch failure | Make memory calls sequentially |
-| Slow first `remember`/`recall` | Embedding model loading on first use | Normal — model loads once per session (~2-3s) |
-
-</details>
-
-## Cost
-
-**Free.** SynaBun uses local embeddings (Transformers.js) and a local SQLite database. No API calls, no cloud services, no usage-based billing.
-
-## File Structure
-
-```
-Synabun/
-├── LICENSE                         # Apache 2.0 License
-├── LICENSE-COMMERCIAL.md           # Commercial licensing (Open Core model)
-├── CONTRIBUTING.md                 # Bug reports, feature requests, and forking guide
-├── CHANGELOG.md                    # Version history
-├── SECURITY.md                     # Security policy
-├── .env.example                    # Example environment configuration
-├── .env                            # API key config (generated by setup wizard, gitignored)
-├── setup.js                        # One-command setup & launch script
-├── README.md                       # This file
-├── CLAUDE.md                       # Claude Code project instructions (gitignored)
-├── public/
-│   ├── synabun.png                 # Logo
-│   └── openclaw-logo-text.png      # OpenClaw bridge logo
-├── data/                           # Runtime data directory
-│   ├── memory.db                   # SQLite database (all memories + vectors)
-│   ├── claude-code-projects.json   # Tracked project paths with hook status
-│   ├── hook-features.json          # Hook feature flags (conversationMemory, greeting, userLearning)
-│   ├── mcp-api-key.json            # API key for HTTP MCP transport
-│   ├── pending-compact/            # PreCompact enforcement flags (per session)
-│   ├── pending-remember/           # Edit tracking flags (per session)
-│   └── precompact/                 # Session transcript cache (pre-compaction)
-├── docs/
-│   ├── usage-guide.md              # Detailed usage patterns & best practices
-│   ├── api-reference.md            # Neural Interface REST API reference
-│   └── hooks.md                    # Claude Code hook system documentation
-├── skills/
-│   ├── synabun/
-│   │   ├── SKILL.md                # /synabun command hub (entry point)
-│   │   └── modules/
-│   │       ├── idea.md             # Brainstorm Ideas module
-│   │       └── audit.md            # Audit Memories module
-│   └── leonardo/
-│       ├── SKILL.md                # /leonardo master media prompter
-│       └── modules/
-│           ├── video-prompter.md   # 5-phase video creation questionnaire
-│           ├── image-prompter.md   # 5-phase image creation questionnaire
-│           ├── model-advisor.md    # Decision matrices for 30+ models
-│           ├── prompt-library.md   # Curated prompt templates
-│           └── style-guide.md      # Style stacking & motion controls
-├── hooks/
-│   └── claude-code/
-│       ├── session-start.mjs       # SessionStart — greeting, boot sequence, compaction recovery, session registration
-│       ├── prompt-submit.mjs       # UserPromptSubmit — tiered recall nudges, loop iteration injection
-│       ├── pre-compact.mjs         # PreCompact — transcript capture before compaction
-│       ├── stop.mjs                # Stop — combined obligations: compaction, loops, task memory, plans
-│       ├── post-remember.mjs       # PostToolUse — edit tracking, flag clearing, user learning
-│       ├── pre-websearch.mjs       # PreToolUse — blocks WebSearch during active browser sessions
-│       └── post-plan.mjs           # PostToolUse — auto-stores plans as memories
-├── memory-seed/                    # Bootstrap seed data for new installations
-│   ├── README.md
-│   ├── architecture/               # 5 architecture overview memories
-│   ├── mcp-tools/                  # 7 tool documentation memories
-│   ├── neural-interface/           # 5 UI/API documentation memories
-│   ├── hooks/                      # 4 hook documentation memories
-│   ├── setup/                      # 3 setup/onboarding memories
-│   └── development/                # 4 development guide memories
-├── .tests/                         # Vitest test suite
-│   ├── vitest.config.ts
-│   ├── unit/                       # Tool-level unit tests (6 files)
-│   ├── scenarios/                  # Usage pattern + cost benchmark tests (5 files)
-│   ├── mocks/                      # SQLite/embedding mocks
-│   └── utils/                      # Test utilities
-├── neural-interface/               # 3D visualization UI (http://localhost:3344)
-│   ├── server.js                   # Express API — 55+ endpoints
-│   ├── package.json
-│   └── public/
-│       ├── index.html              # Three.js force-directed 3D graph
-│       ├── index2d.html            # 2D canvas visualization variant
-│       ├── onboarding.html         # Setup wizard
-│       └── shared/                 # Shared CSS/JS assets
-└── mcp-server/                     # MCP server (Node.js + TypeScript)
-    ├── package.json
-    ├── tsconfig.json
-    ├── run.mjs                     # Entry wrapper (sets cwd, imports dist/)
-    ├── data/
-    │   ├── custom-categories-*.json # Per-connection category definitions
-    │   └── display-settings.json    # MCP response display config
-    ├── dist/                        # Compiled JS (generated by npm run build)
-    └── src/
-        ├── index.ts                 # Tool registration + schema refresh (72 tools)
-        ├── config.ts                # Namespaced env config, project detection
-        ├── types.ts                 # MemoryPayload interface (incl. file_checksums)
-        ├── http.ts                  # HTTP MCP transport
-        ├── tui.ts                   # Terminal UI for interactive management
-        ├── services/
-        │   ├── sqlite.ts            # SQLite storage layer (vectors as Float32 BLOBs)
-        │   ├── local-embeddings.ts  # Local embedding generation (Transformers.js)
-        │   ├── categories.ts        # Category CRUD, hierarchy, descriptions
-        │   └── file-checksums.ts    # SHA-256 hashing for sync tool
-        └── tools/
-            ├── remember.ts          # Store a memory
-            ├── recall.ts            # Semantic search with time decay
-            ├── forget.ts            # Soft-delete (moves to trash)
-            ├── restore.ts           # Restore from trash
-            ├── reflect.ts           # Update a memory
-            ├── memories.ts          # List and stats
-            ├── sync.ts              # Stale memory detection via file hashes
-            ├── category-create.ts   # Create category (triggers schema refresh)
-            ├── category-update.ts   # Edit category (triggers schema refresh)
-            ├── category-delete.ts   # Delete category (triggers schema refresh)
-            ├── category-list.ts     # List categories with hierarchy
-            ├── leonardo.ts          # Leonardo.ai tool registration barrel (4 browser-based tools)
-            └── leonardo-browser-tools.ts # Browser-based generation, library, navigation, download
-```
-
-## License
-
-Licensed under the [Apache License, Version 2.0](./LICENSE).
-
-You are free to use, modify, and distribute SynaBun under Apache 2.0. Premium features and enterprise extensions may be offered under a separate commercial license. See [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md) for details.
-
-## Trademark Notice
-
-"SynaBun" is a trademark of its authors. The license does not grant permission to use the SynaBun name, trademarks, service marks, or branding. If you fork this project, you must use a different name for your derivative work.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/danilokhury/Synabun/main/public/synabun.png" alt="SynaBun" width="120" />
+</p>
+
+<h1 align="center">SynaBun</h1>
+
+<p align="center">
+  Long-term memory for your AI coding tools, stored on your own computer.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/synabun"><img src="https://img.shields.io/npm/v/synabun?color=cb3837&logo=npm&logoColor=white" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/synabun"><img src="https://img.shields.io/npm/dm/synabun?color=cb3837&logo=npm&logoColor=white" alt="npm downloads" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/synabun?color=blue" alt="license" /></a>
+  <a href="https://github.com/danilokhury/Synabun/actions/workflows/ci.yml"><img src="https://github.com/danilokhury/Synabun/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://discord.gg/x6yWqE9GZP"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
+  <a href="https://x.com/SynabunAI"><img src="https://img.shields.io/badge/Follow-%40SynabunAI-000000?logo=x&logoColor=white" alt="X / Twitter" /></a>
+</p>
+
+<p align="center">
+  <a href="https://synabun.ai">synabun.ai</a> · <a href="https://synabun.ai/docs">Docs</a> · <a href="https://synabun.ai/blog">Blog</a> · <a href="https://synabun.ai/compare">Compare</a> · <a href="https://synabun.ai/changelog">Changelog</a>
+</p>
+
+---
+
+SynaBun gives your AI coding tools a memory that lasts. What you decided, fixed and explained in one session is there in the next one, in every project and every tool you connect, so you stop repeating yourself. It all lives in one file on your computer: no account, no cloud service, no API key.
+
+It connects to Claude Code, Codex CLI, Gemini CLI and OpenCode with one switch each, and to Cursor, Windsurf or any other tool that supports MCP (the Model Context Protocol) with a config snippet you copy. It comes with the Neural Interface, a local web app where you see what your tools remember and run your coding agents.
+
+## What you can do with it
+
+- **Keep context between sessions.** Your assistant saves what it learned as it works and looks it up before the next task. Search matches meaning as well as keywords.
+- **See what it knows.** Browse, search, edit and delete memories in the Neural Interface, on a 3D map where related memories sit together.
+- **Run Claude Code, Codex and OpenCode side by side.** Each has a side panel in the Neural Interface, next to terminals, a file explorer and a whiteboard, all sharing the same memory.
+- **Delegate.** The SynaBun Assistant plans a task, proposes a model for it, hands it to a worker in Claude Code, Codex or OpenCode and reports the result. You can also message it from WhatsApp.
+- **Automate.** Save a task as a template, then run it as a loop or on a schedule.
+- **Give agents a browser.** Browser tools let an agent open pages, click, type and read in a browser you can watch.
+
+## Quick start
+
+You need [Node.js](https://nodejs.org) 22.19 or newer.
+
+```bash
+npm install -g synabun
+npm --prefix "$(npm root -g)/synabun/mcp-server" run setup:embeddings
+synabun
+```
+
+1. **Install.** The first command installs SynaBun. The second downloads the model that powers search by meaning; without it SynaBun still works, with keyword search only. In Windows Command Prompt, replace `$(npm root -g)` with the path that `npm root -g` prints.
+2. **Start.** `synabun` starts the Neural Interface at `http://localhost:3344` and opens the setup wizard in your browser. The first start also installs a Chromium build for the browser tools.
+3. **Connect your AI tool.** In the wizard, add your projects and switch on the tools you use. SynaBun registers itself with Claude Code, Codex CLI, Gemini CLI and OpenCode, and installs a short set of rules that tell each tool when to recall and when to remember. For Cursor, Windsurf or another MCP tool, copy the config snippet shown in the same step. You can change the connections later in **Settings → AI connections**.
+4. **Try it.** Start a new session in your AI tool and say:
+
+   > Remember that we deploy from the `release` branch, never from `main`.
+
+   Start another session and ask:
+
+   > What do you remember about how we deploy?
+
+   Then open `http://localhost:3344` to see the memory on the map. Press `/` to search, `a` to open the Assistant, and the **?** button in the title bar for a tour.
+
+Leave `synabun` running while you work: Claude Code reaches its memory through it. Stop it with `Ctrl+C`. If something looks wrong, `synabun doctor` reports the state of your data and your tool connections.
+
+To run from source instead:
+
+```bash
+git clone --depth=1 https://github.com/danilokhury/Synabun.git
+cd Synabun
+npm start
+```
+
+`npm start` installs dependencies, builds the MCP server and starts the app. Once it is up, run `npm --prefix mcp-server run setup:embeddings` in a second terminal to turn on search by meaning.
+
+## How it works
+
+```
+Your AI tool ── MCP ──▶ SynaBun MCP server ──▶ memory.db (SQLite) ◀── Neural Interface (localhost:3344)
+```
+
+- **A local database.** Memories live in one SQLite file on your disk. Each one is indexed for keyword search and for search by meaning, using a model that runs on your machine.
+- **An MCP server.** It gives your AI tool the memory tools: `remember`, `recall`, `reflect`, `forget`, `restore` and a few more. Any MCP client can use it.
+- **The Neural Interface.** A local web app on port 3344 that reads the same database. It holds the memory map, settings, the side panels, the Assistant and your automations.
+- **Rules and hooks.** The installed rules tell each tool to recall before substantial work and to remember after it. In Claude Code, hooks add to that: they bring relevant memories into the session and remind the assistant to save its work.
+
+## Features
+
+### Memory
+
+- **Keyword and meaning search.** `recall` combines both and can return compact results sized to a token budget.
+- **Categories you define.** Each category's description tells the assistant what belongs there.
+- **One memory for every project.** Recall favours the project you are in and still finds what you learned elsewhere.
+- **Hard to lose.** Edits keep a revision history you can undo, deleted memories go to a trash you can restore from, and `sync` flags memories whose source files have changed.
+- **Backups.** Scheduled, checksum-verified backups in **Settings → Memory & backups**. `synabun restore-backup --from <backup.zip>` checks a backup, and adding `--apply` restores it.
+
+### Neural Interface
+
+- **Memory map.** A 3D map of everything stored: top-level categories are continents, categories are islands, and similar memories sit side by side.
+- **Workspace.** Terminals, a file explorer and a whiteboard next to your memories.
+- **Settings you can search**, in English and Brazilian Portuguese.
+- **A workspace tour** behind the **?** button.
+
+### Coding agents
+
+- **Side panels for Claude Code, Codex and OpenCode.** Streaming answers, tool calls, approvals, plans and resumable sessions, on your own accounts. Gemini CLI and plain shells open as terminal tabs.
+- **SynaBun Assistant.** One assistant that recalls memory on every turn, proposes where a task should run, dispatches it to a worker and reads back a structured result. Budget caps and a token gauge keep spending visible.
+- **WhatsApp Link.** Message the Assistant from your phone as a linked device, with three permission levels. See [docs/whatsapp.md](./docs/whatsapp.md).
+- **Computer use on macOS.** The Assistant can see and operate desktop apps, behind guards and stop controls.
+- **Style Guide.** A brand and design system per project, saved as `DESIGN.md` and design tokens. Agents read it and can only propose changes. See [docs/style-guide.md](./docs/style-guide.md).
+
+### Automations and tools
+
+- **Automation Studio and schedules.** Task templates you run as loops or on a schedule.
+- **Browser tools.** Navigate, click, type, read and take screenshots, or batch several actions into one call. See [docs/browser-v2.md](./docs/browser-v2.md).
+- **Integrations.** Tool groups for Discord, Google Search Console, YouTube Studio, Leonardo.ai and Bluesky, and readers for X, Facebook, Instagram, LinkedIn, TikTok and WhatsApp Web. Tool profiles limit a session to the groups it needs.
+- **Skills.** [`/synabun`](./skills/synabun/SKILL.md) brainstorms from memory, audits memories against your code, saves a conversation and creates schedules. [`/leonardo`](./skills/leonardo/SKILL.md) guides image and video prompts.
+- **Claude Code hooks.** How they are installed, isolated and measured: [docs/hook-integrity.md](./docs/hook-integrity.md).
+- **AI decisions (optional).** With your own TypeSafe API key, SynaBun asks for a judgment where a fixed rule would guess: is this memory a duplicate, does it hold a secret, is it stale. Every judgment has a local fallback, and nothing is sent without a key. See [docs/judgments.md](./docs/judgments.md).
+
+## Requirements
+
+- **Node.js 22.19 or newer.**
+- **macOS, Windows or Linux.** Computer use is macOS only.
+- **The coding tools you want to use**, installed and signed in with your own accounts. SynaBun does not include model access.
+- **Optional: C/C++ build tools.** Terminals use a native module. If it has no prebuilt binary for your system, it is compiled during install; if that fails, everything except terminals still works.
+- **Optional: credentials for integrations** such as Discord, YouTube or AI decisions. You enter them in Settings when you turn the feature on.
+
+## Updating
+
+```bash
+npm install -g synabun@latest
+npm --prefix "$(npm root -g)/synabun/mcp-server" run setup:embeddings
+```
+
+SynaBun also offers new versions inside the app. Either way, run the second command after each update: the search model is kept inside the installed package, which the update replaces. If recall reports `Local embeddings unavailable; keyword retrieval used.`, this is the fix.
+
+**Coming from 2026.x?** Run `npm i -g synabun@latest` once by hand. Versions used to be dates (`2026.9.5`) and are now plain semver (`2.0.0`), so the in-app update check of an older install does not offer 2.0.0. From 2.0.0 on, the in-app updater works as before.
+
+**Running from source?** `git pull --ff-only`, then `npm run mcp:build` and `npm start`.
+
+Before a new version starts for the first time, SynaBun takes a verified snapshot of your data and keeps it in `backups/updates` in your data folder. If it cannot take the snapshot, it stops instead of starting.
+
+## Your data and privacy
+
+Everything SynaBun stores is in one folder outside the app: `~/.synabun` on macOS and Linux, `%APPDATA%\synabun` on Windows. Set `SYNABUN_DATA_HOME` to use another place.
+
+```
+~/.synabun/
+├── .env                 # settings and credentials for integrations
+├── data/                # interface state, schedules, logs
+├── backups/             # backups and pre-update snapshots
+└── mcp-data/memory.db   # your memories
+```
+
+- **Your memories stay on your machine.** The database is a local file and the search model runs locally.
+- **What does leave it.** Your AI tools send your prompts, and the memories they recall, to their own providers. Optional features (AI decisions, WhatsApp, Discord, the browser) talk to their services once you set them up. SynaBun checks npm and GitHub for new versions, and the interface loads web fonts and one script from public CDNs.
+- **Keep it on a network you trust.** The Neural Interface has no login and listens on all network interfaces. Do not expose port 3344 to the internet. The full security model is in [SECURITY.md](./SECURITY.md).
+- **Back up from the app.** Copying `memory.db` by hand while SynaBun is running can miss recent writes.
+
+## Links
+
+- [Changelog](./CHANGELOG.md): what is new in 2.0.0 and before
+- [Security](./SECURITY.md): security model and how to report a vulnerability
+- [Contributing](./CONTRIBUTING.md): bug reports and feature requests are welcome as [issues](https://github.com/danilokhury/Synabun/issues); pull requests are not accepted
+- [Website](https://synabun.ai), [docs](https://synabun.ai/docs) and [blog](https://synabun.ai/blog)
+- Community: [Discord](https://discord.gg/x6yWqE9GZP) and [X](https://x.com/SynabunAI)
+
+## License
+
+Licensed under the [Apache License, Version 2.0](./LICENSE).
+
+You are free to use, modify, and distribute SynaBun under Apache 2.0. Premium features and enterprise extensions may be offered under a separate commercial license. See [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md) for details. Third-party notices are in [NOTICE](./NOTICE) and [THIRD-PARTY-LICENSES.md](./THIRD-PARTY-LICENSES.md).
+
+## Trademark Notice
+
+"SynaBun" is a trademark of its authors. The license does not grant permission to use the SynaBun name, trademarks, service marks, or branding. If you fork this project, you must use a different name for your derivative work.