synabun 2026.5.14 → 2026.7.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (383) hide show
  1. package/CHANGELOG.md +40 -202
  2. package/LICENSE-COMMERCIAL.md +33 -0
  3. package/NOTICE +17 -0
  4. package/README.md +926 -991
  5. package/THIRD-PARTY-LICENSES.md +93 -0
  6. package/bin/synabun.js +30 -0
  7. package/hooks/claude-code/post-plan.mjs +65 -28
  8. package/hooks/claude-code/pre-compact.mjs +2 -1
  9. package/hooks/claude-code/prompt-submit.mjs +1070 -1047
  10. package/hooks/claude-code/session-start.mjs +15 -9
  11. package/hooks/claude-code/shared.mjs +634 -419
  12. package/hooks/claude-code/stop.mjs +115 -97
  13. package/hooks/claude-code/subagent-start.mjs +72 -0
  14. package/hooks/claude-code/subagent-stop.mjs +99 -0
  15. package/lib/client-config-repair.js +136 -0
  16. package/lib/data-home-migration.js +498 -0
  17. package/lib/paths.d.ts +21 -0
  18. package/lib/paths.js +45 -16
  19. package/mcp-server/dist/config.d.ts +1 -0
  20. package/mcp-server/dist/config.d.ts.map +1 -1
  21. package/mcp-server/dist/config.js +5 -2
  22. package/mcp-server/dist/config.js.map +1 -1
  23. package/mcp-server/dist/http.d.ts +11 -1
  24. package/mcp-server/dist/http.d.ts.map +1 -1
  25. package/mcp-server/dist/http.js +172 -33
  26. package/mcp-server/dist/http.js.map +1 -1
  27. package/mcp-server/dist/index.d.ts +2 -0
  28. package/mcp-server/dist/index.d.ts.map +1 -1
  29. package/mcp-server/dist/index.js +89 -52
  30. package/mcp-server/dist/index.js.map +1 -1
  31. package/mcp-server/dist/preload-http.js +8 -6
  32. package/mcp-server/dist/preload-http.js.map +1 -1
  33. package/mcp-server/dist/preload.js +8 -6
  34. package/mcp-server/dist/preload.js.map +1 -1
  35. package/mcp-server/dist/services/categories.d.ts +2 -2
  36. package/mcp-server/dist/services/categories.d.ts.map +1 -1
  37. package/mcp-server/dist/services/categories.js +37 -16
  38. package/mcp-server/dist/services/categories.js.map +1 -1
  39. package/mcp-server/dist/services/codex-config-heal.d.ts +49 -0
  40. package/mcp-server/dist/services/codex-config-heal.d.ts.map +1 -0
  41. package/mcp-server/dist/services/codex-config-heal.js +335 -0
  42. package/mcp-server/dist/services/codex-config-heal.js.map +1 -0
  43. package/mcp-server/dist/services/fb-regions.d.ts +71 -0
  44. package/mcp-server/dist/services/fb-regions.d.ts.map +1 -0
  45. package/mcp-server/dist/services/fb-regions.js +211 -0
  46. package/mcp-server/dist/services/fb-regions.js.map +1 -0
  47. package/mcp-server/dist/services/identity.d.ts +84 -0
  48. package/mcp-server/dist/services/identity.d.ts.map +1 -0
  49. package/mcp-server/dist/services/identity.js +187 -0
  50. package/mcp-server/dist/services/identity.js.map +1 -0
  51. package/mcp-server/dist/services/local-embeddings.d.ts.map +1 -1
  52. package/mcp-server/dist/services/local-embeddings.js +5 -0
  53. package/mcp-server/dist/services/local-embeddings.js.map +1 -1
  54. package/mcp-server/dist/services/neural-interface.d.ts +102 -12
  55. package/mcp-server/dist/services/neural-interface.d.ts.map +1 -1
  56. package/mcp-server/dist/services/neural-interface.js +398 -86
  57. package/mcp-server/dist/services/neural-interface.js.map +1 -1
  58. package/mcp-server/dist/services/profiles.d.ts +18 -0
  59. package/mcp-server/dist/services/profiles.d.ts.map +1 -1
  60. package/mcp-server/dist/services/profiles.js +120 -110
  61. package/mcp-server/dist/services/profiles.js.map +1 -1
  62. package/mcp-server/dist/services/sqlite.d.ts +142 -0
  63. package/mcp-server/dist/services/sqlite.d.ts.map +1 -1
  64. package/mcp-server/dist/services/sqlite.js +651 -183
  65. package/mcp-server/dist/services/sqlite.js.map +1 -1
  66. package/mcp-server/dist/services/vector-cache.d.ts +62 -0
  67. package/mcp-server/dist/services/vector-cache.d.ts.map +1 -0
  68. package/mcp-server/dist/services/vector-cache.js +196 -0
  69. package/mcp-server/dist/services/vector-cache.js.map +1 -0
  70. package/mcp-server/dist/tools/bluesky.d.ts +23 -0
  71. package/mcp-server/dist/tools/bluesky.d.ts.map +1 -0
  72. package/mcp-server/dist/tools/bluesky.js +970 -0
  73. package/mcp-server/dist/tools/bluesky.js.map +1 -0
  74. package/mcp-server/dist/tools/browser-cheatsheet.d.ts +4 -4
  75. package/mcp-server/dist/tools/browser-cheatsheet.d.ts.map +1 -1
  76. package/mcp-server/dist/tools/browser-cheatsheet.js +42 -14
  77. package/mcp-server/dist/tools/browser-cheatsheet.js.map +1 -1
  78. package/mcp-server/dist/tools/browser-interact.d.ts +38 -19
  79. package/mcp-server/dist/tools/browser-interact.d.ts.map +1 -1
  80. package/mcp-server/dist/tools/browser-interact.js +82 -37
  81. package/mcp-server/dist/tools/browser-interact.js.map +1 -1
  82. package/mcp-server/dist/tools/browser-navigate.d.ts +3 -1
  83. package/mcp-server/dist/tools/browser-navigate.d.ts.map +1 -1
  84. package/mcp-server/dist/tools/browser-navigate.js +38 -5
  85. package/mcp-server/dist/tools/browser-navigate.js.map +1 -1
  86. package/mcp-server/dist/tools/browser-observe.d.ts +131 -20
  87. package/mcp-server/dist/tools/browser-observe.d.ts.map +1 -1
  88. package/mcp-server/dist/tools/browser-observe.js +1229 -715
  89. package/mcp-server/dist/tools/browser-observe.js.map +1 -1
  90. package/mcp-server/dist/tools/browser.d.ts +3 -2
  91. package/mcp-server/dist/tools/browser.d.ts.map +1 -1
  92. package/mcp-server/dist/tools/browser.js +12 -3
  93. package/mcp-server/dist/tools/browser.js.map +1 -1
  94. package/mcp-server/dist/tools/choice.d.ts +160 -0
  95. package/mcp-server/dist/tools/choice.d.ts.map +1 -0
  96. package/mcp-server/dist/tools/choice.js +80 -0
  97. package/mcp-server/dist/tools/choice.js.map +1 -0
  98. package/mcp-server/dist/tools/fb-groups.d.ts +98 -0
  99. package/mcp-server/dist/tools/fb-groups.d.ts.map +1 -0
  100. package/mcp-server/dist/tools/fb-groups.js +369 -0
  101. package/mcp-server/dist/tools/fb-groups.js.map +1 -0
  102. package/mcp-server/dist/tools/forget.js +1 -1
  103. package/mcp-server/dist/tools/forget.js.map +1 -1
  104. package/mcp-server/dist/tools/gsc/performance.d.ts +2 -2
  105. package/mcp-server/dist/tools/loop.d.ts.map +1 -1
  106. package/mcp-server/dist/tools/loop.js +57 -13
  107. package/mcp-server/dist/tools/loop.js.map +1 -1
  108. package/mcp-server/dist/tools/memories.d.ts +6 -3
  109. package/mcp-server/dist/tools/memories.d.ts.map +1 -1
  110. package/mcp-server/dist/tools/memories.js +19 -4
  111. package/mcp-server/dist/tools/memories.js.map +1 -1
  112. package/mcp-server/dist/tools/morelogin.d.ts +24 -0
  113. package/mcp-server/dist/tools/morelogin.d.ts.map +1 -0
  114. package/mcp-server/dist/tools/morelogin.js +79 -0
  115. package/mcp-server/dist/tools/morelogin.js.map +1 -0
  116. package/mcp-server/dist/tools/profile.d.ts +1 -1
  117. package/mcp-server/dist/tools/profile.d.ts.map +1 -1
  118. package/mcp-server/dist/tools/profile.js +25 -10
  119. package/mcp-server/dist/tools/profile.js.map +1 -1
  120. package/mcp-server/dist/tools/recall.d.ts.map +1 -1
  121. package/mcp-server/dist/tools/recall.js +3 -9
  122. package/mcp-server/dist/tools/recall.js.map +1 -1
  123. package/mcp-server/dist/tools/reflect.js +1 -1
  124. package/mcp-server/dist/tools/reflect.js.map +1 -1
  125. package/mcp-server/dist/tools/remember.d.ts +3 -3
  126. package/mcp-server/dist/tools/remember.d.ts.map +1 -1
  127. package/mcp-server/dist/tools/remember.js +28 -9
  128. package/mcp-server/dist/tools/remember.js.map +1 -1
  129. package/mcp-server/dist/tools/style-guide-tools.d.ts +16 -0
  130. package/mcp-server/dist/tools/style-guide-tools.d.ts.map +1 -0
  131. package/mcp-server/dist/tools/style-guide-tools.js +102 -0
  132. package/mcp-server/dist/tools/style-guide-tools.js.map +1 -0
  133. package/mcp-server/dist/tools/style-guide.d.ts +7 -0
  134. package/mcp-server/dist/tools/style-guide.d.ts.map +1 -0
  135. package/mcp-server/dist/tools/style-guide.js +11 -0
  136. package/mcp-server/dist/tools/style-guide.js.map +1 -0
  137. package/mcp-server/dist/tools/whiteboard-tools.d.ts +6 -6
  138. package/mcp-server/dist/tools/youtube/analytics.d.ts +46 -0
  139. package/mcp-server/dist/tools/youtube/analytics.d.ts.map +1 -0
  140. package/mcp-server/dist/tools/youtube/analytics.js +83 -0
  141. package/mcp-server/dist/tools/youtube/analytics.js.map +1 -0
  142. package/mcp-server/dist/tools/youtube/dedup.d.ts +35 -0
  143. package/mcp-server/dist/tools/youtube/dedup.d.ts.map +1 -0
  144. package/mcp-server/dist/tools/youtube/dedup.js +56 -0
  145. package/mcp-server/dist/tools/youtube/dedup.js.map +1 -0
  146. package/mcp-server/dist/tools/youtube/download.d.ts +31 -0
  147. package/mcp-server/dist/tools/youtube/download.d.ts.map +1 -0
  148. package/mcp-server/dist/tools/youtube/download.js +30 -0
  149. package/mcp-server/dist/tools/youtube/download.js.map +1 -0
  150. package/mcp-server/dist/tools/youtube/helpers.d.ts +66 -0
  151. package/mcp-server/dist/tools/youtube/helpers.d.ts.map +1 -0
  152. package/mcp-server/dist/tools/youtube/helpers.js +143 -0
  153. package/mcp-server/dist/tools/youtube/helpers.js.map +1 -0
  154. package/mcp-server/dist/tools/youtube/media.d.ts +43 -0
  155. package/mcp-server/dist/tools/youtube/media.d.ts.map +1 -0
  156. package/mcp-server/dist/tools/youtube/media.js +97 -0
  157. package/mcp-server/dist/tools/youtube/media.js.map +1 -0
  158. package/mcp-server/dist/tools/youtube/metadata.d.ts +33 -0
  159. package/mcp-server/dist/tools/youtube/metadata.d.ts.map +1 -0
  160. package/mcp-server/dist/tools/youtube/metadata.js +106 -0
  161. package/mcp-server/dist/tools/youtube/metadata.js.map +1 -0
  162. package/mcp-server/dist/tools/youtube/navigate.d.ts +30 -0
  163. package/mcp-server/dist/tools/youtube/navigate.d.ts.map +1 -0
  164. package/mcp-server/dist/tools/youtube/navigate.js +71 -0
  165. package/mcp-server/dist/tools/youtube/navigate.js.map +1 -0
  166. package/mcp-server/dist/tools/youtube/playlist.d.ts +29 -0
  167. package/mcp-server/dist/tools/youtube/playlist.d.ts.map +1 -0
  168. package/mcp-server/dist/tools/youtube/playlist.js +128 -0
  169. package/mcp-server/dist/tools/youtube/playlist.js.map +1 -0
  170. package/mcp-server/dist/tools/youtube/schedule.d.ts +31 -0
  171. package/mcp-server/dist/tools/youtube/schedule.d.ts.map +1 -0
  172. package/mcp-server/dist/tools/youtube/schedule.js +147 -0
  173. package/mcp-server/dist/tools/youtube/schedule.js.map +1 -0
  174. package/mcp-server/dist/tools/youtube/source.d.ts +36 -0
  175. package/mcp-server/dist/tools/youtube/source.d.ts.map +1 -0
  176. package/mcp-server/dist/tools/youtube/source.js +85 -0
  177. package/mcp-server/dist/tools/youtube/source.js.map +1 -0
  178. package/mcp-server/dist/tools/youtube/upload.d.ts +53 -0
  179. package/mcp-server/dist/tools/youtube/upload.d.ts.map +1 -0
  180. package/mcp-server/dist/tools/youtube/upload.js +255 -0
  181. package/mcp-server/dist/tools/youtube/upload.js.map +1 -0
  182. package/mcp-server/dist/tools/youtube.d.ts +12 -0
  183. package/mcp-server/dist/tools/youtube.d.ts.map +1 -0
  184. package/mcp-server/dist/tools/youtube.js +38 -0
  185. package/mcp-server/dist/tools/youtube.js.map +1 -0
  186. package/mcp-server/dist/tui.js +3 -4
  187. package/mcp-server/dist/tui.js.map +1 -1
  188. package/mcp-server/package-lock.json +4798 -0
  189. package/mcp-server/package.json +54 -44
  190. package/mcp-server/run.mjs +11 -6
  191. package/mcp-server/src/config.ts +11 -7
  192. package/mcp-server/src/http.ts +265 -110
  193. package/mcp-server/src/index.ts +86 -49
  194. package/mcp-server/src/preload-http.ts +19 -18
  195. package/mcp-server/src/preload.ts +19 -18
  196. package/mcp-server/src/services/categories.ts +36 -19
  197. package/mcp-server/src/services/codex-config-heal.ts +389 -0
  198. package/mcp-server/src/services/fb-regions.ts +221 -0
  199. package/mcp-server/src/services/identity.ts +230 -0
  200. package/mcp-server/src/services/local-embeddings.ts +5 -0
  201. package/mcp-server/src/services/neural-interface.ts +464 -96
  202. package/mcp-server/src/services/profiles.ts +119 -106
  203. package/mcp-server/src/services/sqlite.ts +1405 -823
  204. package/mcp-server/src/services/vector-cache.ts +199 -0
  205. package/mcp-server/src/tools/bluesky.ts +1006 -0
  206. package/mcp-server/src/tools/browser-cheatsheet.ts +44 -14
  207. package/mcp-server/src/tools/browser-interact.ts +294 -244
  208. package/mcp-server/src/tools/browser-navigate.ts +37 -5
  209. package/mcp-server/src/tools/browser-observe.ts +2018 -1472
  210. package/mcp-server/src/tools/browser.ts +18 -2
  211. package/mcp-server/src/tools/choice.ts +103 -0
  212. package/mcp-server/src/tools/fb-groups.ts +387 -0
  213. package/mcp-server/src/tools/forget.ts +1 -1
  214. package/mcp-server/src/tools/loop.ts +56 -14
  215. package/mcp-server/src/tools/memories.ts +19 -4
  216. package/mcp-server/src/tools/morelogin.ts +81 -0
  217. package/mcp-server/src/tools/profile.ts +24 -10
  218. package/mcp-server/src/tools/recall.ts +3 -9
  219. package/mcp-server/src/tools/reflect.ts +145 -145
  220. package/mcp-server/src/tools/remember.ts +137 -115
  221. package/mcp-server/src/tools/style-guide-tools.ts +129 -0
  222. package/mcp-server/src/tools/style-guide.ts +15 -0
  223. package/mcp-server/src/tools/youtube/analytics.ts +106 -0
  224. package/mcp-server/src/tools/youtube/dedup.ts +57 -0
  225. package/mcp-server/src/tools/youtube/download.ts +41 -0
  226. package/mcp-server/src/tools/youtube/helpers.ts +183 -0
  227. package/mcp-server/src/tools/youtube/media.ts +109 -0
  228. package/mcp-server/src/tools/youtube/metadata.ts +112 -0
  229. package/mcp-server/src/tools/youtube/navigate.ts +81 -0
  230. package/mcp-server/src/tools/youtube/playlist.ts +134 -0
  231. package/mcp-server/src/tools/youtube/schedule.ts +158 -0
  232. package/mcp-server/src/tools/youtube/source.ts +101 -0
  233. package/mcp-server/src/tools/youtube/upload.ts +296 -0
  234. package/mcp-server/src/tools/youtube.ts +47 -0
  235. package/mcp-server/src/tui.ts +5 -6
  236. package/neural-interface/lib/backup-service.js +604 -0
  237. package/neural-interface/lib/browser-tab-recovery.js +119 -0
  238. package/neural-interface/lib/claude-agent-bridge.js +1180 -0
  239. package/neural-interface/lib/claude-model-catalog.js +341 -0
  240. package/neural-interface/lib/codex-collaboration-mode.js +14 -0
  241. package/neural-interface/lib/codex-mcp-approvals.js +56 -0
  242. package/neural-interface/lib/codex-request-journal.js +242 -0
  243. package/neural-interface/lib/codex-runtime-path.js +146 -0
  244. package/neural-interface/lib/codex-session-catalog.js +220 -0
  245. package/neural-interface/lib/codex-sidepanel-permissions.js +110 -0
  246. package/neural-interface/lib/db.js +274 -65
  247. package/neural-interface/lib/design-md.js +179 -0
  248. package/neural-interface/lib/exec-loop-command.js +215 -0
  249. package/neural-interface/lib/loop-logger.js +32 -8
  250. package/neural-interface/lib/mcp-client-config.js +53 -0
  251. package/neural-interface/lib/memo-cache.js +84 -0
  252. package/neural-interface/lib/morelogin.js +277 -0
  253. package/neural-interface/lib/native-loop-providers.js +508 -0
  254. package/neural-interface/lib/native-loop-runtime.js +658 -0
  255. package/neural-interface/lib/opencode-history.js +253 -0
  256. package/neural-interface/lib/opencode-runtime-config.js +40 -0
  257. package/neural-interface/lib/opencode-v2-client.js +92 -1
  258. package/neural-interface/lib/project-storage.js +766 -0
  259. package/neural-interface/lib/schedule-launch-intent.js +40 -0
  260. package/neural-interface/lib/session-cache-builder.js +52 -26
  261. package/neural-interface/lib/session-indexer.js +657 -651
  262. package/neural-interface/lib/session-title-generator.js +228 -0
  263. package/neural-interface/lib/skill-prompt-bridge.js +11 -0
  264. package/neural-interface/lib/ui-blob-store.js +106 -0
  265. package/neural-interface/lib/vector-cache.js +185 -0
  266. package/neural-interface/package-lock.json +4645 -0
  267. package/neural-interface/package.json +55 -33
  268. package/neural-interface/public/apple-touch-icon.png +0 -0
  269. package/neural-interface/public/category-logos/synabun.png +0 -0
  270. package/neural-interface/public/claude-chat.js +1183 -1174
  271. package/neural-interface/public/favicon-16x16.png +0 -0
  272. package/neural-interface/public/favicon-32x32.png +0 -0
  273. package/neural-interface/public/icon-192.png +0 -0
  274. package/neural-interface/public/icon-512.png +0 -0
  275. package/neural-interface/public/index.html +2 -2
  276. package/neural-interface/public/index2d.html +2 -2
  277. package/neural-interface/public/logo-synabun.png +0 -0
  278. package/neural-interface/public/logoHD.png +0 -0
  279. package/neural-interface/public/onboarding.html +82 -29
  280. package/neural-interface/public/shared/agent-runtime-options.js +437 -0
  281. package/neural-interface/public/shared/api.js +107 -50
  282. package/neural-interface/public/shared/blob-store.js +99 -0
  283. package/neural-interface/public/shared/cdx/cdx-icons.js +11 -2
  284. package/neural-interface/public/shared/cdx/cdx-panel.js +287 -40
  285. package/neural-interface/public/shared/cdx/cdx-protocol.js +443 -0
  286. package/neural-interface/public/shared/cdx/cdx-render.js +311 -112
  287. package/neural-interface/public/shared/cdx/cdx-requests.js +259 -49
  288. package/neural-interface/public/shared/cdx/cdx-styles.js +512 -19
  289. package/neural-interface/public/shared/cdx/cdx-tabs.js +2027 -399
  290. package/neural-interface/public/shared/cdx/cdx-ws.js +63 -23
  291. package/neural-interface/public/shared/cli-status.js +1 -0
  292. package/neural-interface/public/shared/cp/cp-agents.js +166 -0
  293. package/neural-interface/public/shared/cp/cp-bash.js +216 -0
  294. package/neural-interface/public/shared/cp/cp-ctx.js +11 -0
  295. package/neural-interface/public/shared/cp/cp-diff.js +223 -0
  296. package/neural-interface/public/shared/cp/cp-permissions.js +309 -0
  297. package/neural-interface/public/shared/cp/cp-statusline.js +122 -0
  298. package/neural-interface/public/shared/cp/cp-styles.js +148 -0
  299. package/neural-interface/public/shared/html-shell.js +15 -1
  300. package/neural-interface/public/shared/node-positions-store.js +44 -0
  301. package/neural-interface/public/shared/ocp/ocp-panel.js +36 -37
  302. package/neural-interface/public/shared/ocp/ocp-questions.js +48 -0
  303. package/neural-interface/public/shared/ocp/ocp-render.js +77 -69
  304. package/neural-interface/public/shared/ocp/ocp-send.js +19 -2
  305. package/neural-interface/public/shared/ocp/ocp-styles.js +39 -3
  306. package/neural-interface/public/shared/ocp/ocp-tabs.js +27 -11
  307. package/neural-interface/public/shared/ocp-v2/ocp-v2-automation-ownership.js +54 -0
  308. package/neural-interface/public/shared/ocp-v2/ocp-v2-childpanel.js +7 -1
  309. package/neural-interface/public/shared/ocp-v2/ocp-v2-compact-button.js +5 -1
  310. package/neural-interface/public/shared/ocp-v2/ocp-v2-manager.js +22 -8
  311. package/neural-interface/public/shared/ocp-v2/ocp-v2-panel.js +456 -23
  312. package/neural-interface/public/shared/ocp-v2/ocp-v2-plan.js +12 -6
  313. package/neural-interface/public/shared/ocp-v2/ocp-v2-profile-inheritance.js +64 -0
  314. package/neural-interface/public/shared/ocp-v2/ocp-v2-projectbar.js +100 -24
  315. package/neural-interface/public/shared/ocp-v2/ocp-v2-render.js +42 -62
  316. package/neural-interface/public/shared/ocp-v2/ocp-v2-send.js +38 -4
  317. package/neural-interface/public/shared/ocp-v2/ocp-v2-state.js +4 -1
  318. package/neural-interface/public/shared/ocp-v2/ocp-v2-styles.js +16 -6
  319. package/neural-interface/public/shared/ocp-v2/ocp-v2-ws.js +24 -9
  320. package/neural-interface/public/shared/session-title.js +100 -0
  321. package/neural-interface/public/shared/storage.js +13 -0
  322. package/neural-interface/public/shared/styles.css +26136 -24860
  323. package/neural-interface/public/shared/term-renderer.js +206 -0
  324. package/neural-interface/public/shared/ui-automation-studio.js +4891 -4780
  325. package/neural-interface/public/shared/ui-claude-panel.js +9947 -8770
  326. package/neural-interface/public/shared/ui-codex-panel.js +7 -1
  327. package/neural-interface/public/shared/ui-detail.js +65 -11
  328. package/neural-interface/public/shared/ui-explorer.js +378 -218
  329. package/neural-interface/public/shared/ui-file-explorer.js +187 -83
  330. package/neural-interface/public/shared/ui-menubar.js +13 -0
  331. package/neural-interface/public/shared/ui-native-loop-router-state.js +94 -0
  332. package/neural-interface/public/shared/ui-native-loop-router.js +438 -0
  333. package/neural-interface/public/shared/ui-native-window-id.js +7 -0
  334. package/neural-interface/public/shared/ui-navbar.js +261 -242
  335. package/neural-interface/public/shared/ui-opencode-panel-v2.js +2 -0
  336. package/neural-interface/public/shared/ui-opencode-panel.js +3 -3
  337. package/neural-interface/public/shared/ui-panels.js +15 -7
  338. package/neural-interface/public/shared/ui-resume.js +78 -27
  339. package/neural-interface/public/shared/ui-schedule-queue.js +172 -0
  340. package/neural-interface/public/shared/ui-schedules-studio.js +363 -110
  341. package/neural-interface/public/shared/ui-scroll-follow.js +194 -0
  342. package/neural-interface/public/shared/ui-sessions.js +2 -1
  343. package/neural-interface/public/shared/ui-settings.js +9402 -8301
  344. package/neural-interface/public/shared/ui-sidepanel-layout.js +9 -0
  345. package/neural-interface/public/shared/ui-sidepanel-tray.js +59 -12
  346. package/neural-interface/public/shared/ui-styleguide.js +764 -0
  347. package/neural-interface/public/shared/ui-sync.js +68 -26
  348. package/neural-interface/public/shared/ui-terminal.js +6706 -6710
  349. package/neural-interface/public/shared/ui-tooltip.js +15 -1
  350. package/neural-interface/public/shared/ui-tutorial-steps.js +10 -27
  351. package/neural-interface/public/shared/ui-update.js +159 -51
  352. package/neural-interface/public/shared/ui-whiteboard.js +143 -20
  353. package/neural-interface/public/shared/ui-workspaces.js +2 -1
  354. package/neural-interface/public/shared/utils.js +58 -0
  355. package/neural-interface/public/shared/vterm-buffer.js +21 -12
  356. package/neural-interface/public/synabun.png +0 -0
  357. package/neural-interface/public/variant/2d/graph.js +1683 -1635
  358. package/neural-interface/public/variant/2d/layout.js +595 -594
  359. package/neural-interface/public/variant/2d/main.js +534 -514
  360. package/neural-interface/public/variant/3d/graph.js +2580 -2400
  361. package/neural-interface/public/variant/3d/main.js +513 -492
  362. package/neural-interface/public/vendor/xterm/manifest.json +3 -0
  363. package/neural-interface/public/vendor/xterm/xterm-6.0.0.css +285 -0
  364. package/neural-interface/public/vendor/xterm/xterm-6.0.0.min.js +192 -0
  365. package/neural-interface/scripts/build-vendor.mjs +38 -0
  366. package/neural-interface/scripts/vendor-xterm-entry.js +8 -0
  367. package/neural-interface/server.js +33885 -25856
  368. package/neural-interface/templates/CLAUDE-template.md +251 -241
  369. package/neural-interface/templates/ruleset-versions.json +15 -15
  370. package/package.json +47 -15
  371. package/scripts/recover-user-config.mjs +254 -0
  372. package/scripts/restore-data-home-from-backup.mjs +225 -0
  373. package/setup.js +335 -44
  374. package/skills/synabun/SKILL.md +209 -209
  375. package/skills/synabun/icon.png +0 -0
  376. package/skills/synabun/modules/audit.md +380 -380
  377. package/skills/synabun/modules/idea.md +133 -133
  378. package/skills/synabun/modules/schedule.md +138 -225
  379. package/skills/synabun/synabunicon.png +0 -0
  380. package/updater.mjs +16 -1
  381. package/hooks/claude-code/test-user-learning.mjs +0 -533
  382. package/neural-interface/public/index-legacy.html +0 -14677
  383. package/neural-interface/public/index2d-legacy.html +0 -8193
package/README.md CHANGED
@@ -1,991 +1,926 @@
1
- <p align="center">
2
- <img src="public/synabun.png" alt="SynaBun" width="120" />
3
- </p>
4
-
5
- <h1 align="center">SynaBun</h1>
6
-
7
- <p align="center">
8
- Persistent vector memory for AI assistants — powered by SQLite and local embeddings.
9
- </p>
10
-
11
- <p align="center">
12
- <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>
13
- <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>
14
- <a href="./LICENSE"><img src="https://img.shields.io/npm/l/synabun?color=blue" alt="license" /></a>
15
- <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>
16
- <a href="https://discord.gg/x6yWqE9GZP"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
17
- <a href="https://x.com/SynabunAI"><img src="https://img.shields.io/badge/Follow-%40SynabunAI-000000?logo=x&logoColor=white" alt="X / Twitter" /></a>
18
- <img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+" />
19
- <img src="https://img.shields.io/badge/MCP-Protocol-8B5CF6" alt="MCP Protocol" />
20
- <img src="https://img.shields.io/badge/SQLite-Database-003B57?logo=sqlite&logoColor=white" alt="SQLite" />
21
- </p>
22
-
23
- <p align="center">
24
- <a href="https://synabun.ai">synabun.ai</a>
25
- </p>
26
-
27
- ---
28
-
29
- Any Claude Code, Codex, Gemini, OpenCode, Cursor, Windsurf, or MCP-compatible AI tool can connect to SynaBun and retain knowledge across sessions through semantic vector search. Dedicated sidepanels ship for Claude Code, Codex, and OpenCode with tool activity docks, per-agent abort, permission cards, context gauges, and Multi-CLI Resume. Memories are stored in a local SQLite database with built-in vector search — no external services, no API keys, no Docker.
30
-
31
- ## Screenshots
32
-
33
- <table>
34
- <tr>
35
- <td align="center" width="50%">
36
- <strong>Neural Interface</strong><br><br>
37
- <img src="docs/screenshots/neural-interface.png" alt="3D memory graph visualization" width="100%" />
38
- <br><em>Interactive 3D force-directed graph — memories as nodes, relationships as edges</em>
39
- </td>
40
- <td align="center" width="50%">
41
- <strong>Claude Code Skin</strong><br><br>
42
- <img src="docs/screenshots/claude-code-skin.png" alt="Claude Code side panel skin" width="100%" />
43
- <br><em>Side panel UI for browsing and managing memories alongside your editor</em>
44
- </td>
45
- </tr>
46
- <tr>
47
- <td align="center" width="50%">
48
- <strong>Terminal & Editor</strong><br><br>
49
- <img src="docs/screenshots/terminal-editor.png" alt="Claude Code terminal with memory tools" width="100%" />
50
- <br><em>Memory tools running directly in your terminal alongside code</em>
51
- </td>
52
- <td align="center" width="50%">
53
- <strong>Automation Studio</strong><br><br>
54
- <img src="docs/screenshots/automation-studio.png" alt="Automation studio for background tasks" width="100%" />
55
- <br><em>Autonomous background loops — set a task and let it run</em>
56
- </td>
57
- </tr>
58
- </table>
59
-
60
- ## Features
61
-
62
- - **Semantic Search** — find memories by meaning, not keywords, using cosine similarity
63
- - **Recall Profile Presets** — Quick, Balanced, Deep, and Custom profiles with 6 fine-tune controls, an impact indicator (tokens/recall, memories reachable, session context), and configurable server-side defaults
64
- - **Multi-Project** — single collection serves all projects with automatic project detection and cross-project recall
65
- - **Smart Relevance** — time decay (90-day half-life), project boost (1.2x), and access frequency scoring
66
- - **User-Defined Categories** — hierarchical categories with prescriptive routing descriptions; dynamic schema refresh without server restart
67
- - **Neural Interface** — interactive 3D force-directed graph visualization at `localhost:3344`
68
- - **Local Embeddings** — built-in Transformers.js (`all-MiniLM-L6-v2`, 384 dims) — no API key or internet needed after first run
69
- - **Onboarding Wizard** — guided setup through the Neural Interface UI
70
- - **Trash & Restore** — soft-delete with full restore capability; trash management via Neural Interface
71
- - **Memory Sync** — SHA-256 file hash tracking detects when related source files change, flagging stale memories
72
- - **OpenClaw Bridge** — read-only integration overlays OpenClaw workspace memories as ephemeral nodes in the 3D graph
73
- - **Category Logos** — upload custom logos for parent categories, rendered on sun nodes in the 3D visualization
74
- - **Backup & Restore** — export and import SQLite database snapshots via the Neural Interface
75
- - **Multi-CLI Sidepanels** — dedicated sidepanels for Claude Code, Codex, and OpenCode with per-agent abort, tool activity docks, permission cards, TODO drawer, context gauge, session menu, new-session modal with project + branch selection, and Multi-CLI Resume with provider picker
76
- - **Automation Studio** — visual template editor with user-created collapsible folders (drag/drop, icons, colors), per-template launch defaults (CLI / Model / Thinking effort / MCP profile), and first-class 4-CLI support (Claude Code, Codex, Gemini, OpenCode)
77
- - **Universal MCP Management** — smart-paste add form auto-detects 5 config formats, syncs one MCP server across Claude Code / Codex / Gemini / OpenCode, centralized env vault with sensitive-value masking, auto profile registration, and one-click install from GitHub
78
- - **Claude Code Hooks** — 7 lifecycle hooks automate memory recall, storage, and session indexing
79
- - **User Learning** — 5 binding directives that observe user communication patterns, preferences, and behavioral singularity across sessions (Priority 7 nudge, feature flag, threshold controls)
80
- - **Hybrid Resume Search** — FTS5 + semantic search across saved sessions so old conversations can be resumed across CLIs
81
- - **Multi-Runtime Skills** — `/synabun` command hub and `/leonardo` media prompter work on both Claude Code and Codex; `/synabun changelog` quick action available from the OpenCode sidepanel
82
- - **Leonardo AI Integration** — 5 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
83
- - **Enhanced Browser Tooling** — new `browser_cheatsheet` tool with curated selectors per platform, snapshot modes + viewport filtering, `returnSnapshot` that folds actions and observations into one call, selector auto-heal via `textHint`, and CLI/sidepanel session isolation
84
- - **Modern Code Rendering** — syntax highlighting, file path linkification, language labels, hover-only copy buttons, 30fps throttled streaming, and real-time thinking block streaming across every sidepanel
85
-
86
- ## Table of Contents
87
-
88
- - [Screenshots](#screenshots)
89
- - [Quick Start](#quick-start)
90
- - [Architecture](#architecture)
91
- - [MCP Tools](#mcp-tools)
92
- - [Neural Interface](#neural-interface)
93
- - [Usage](#usage)
94
- - [Memory Categories](#memory-categories)
95
- - [Importance Scale](#importance-scale)
96
- - [How It Works](#how-it-works)
97
- - [Configuration](#configuration)
98
- - [Claude Code Hooks](#claude-code-hooks)
99
- - [Claude Code Skills](#claude-code-skills)
100
- - [CLAUDE.md Integration](#claudemd-integration)
101
- - [Multi-Project Support](#multi-project-support)
102
- - [Known Limitations](#known-limitations)
103
- - [Troubleshooting](#troubleshooting)
104
- - [Cost](#cost)
105
- - [File Structure](#file-structure)
106
- - [License](#license)
107
-
108
- ## Documentation
109
-
110
- | Document | Description |
111
- |----------|-------------|
112
- | **[Website Docs](https://synabun.ai/docs.html)** | Full documentation on synabun.ai |
113
- | **[README](./README.md)** | Quick start, architecture, configuration |
114
- | **[Usage Guide](./docs/usage-guide.md)** | Detailed usage patterns, tool quirks, best practices |
115
- | **[API Reference](./docs/api-reference.md)** | Neural Interface REST API (55+ endpoints) |
116
- | **[Hooks Guide](./docs/hooks.md)** | Claude Code hooks: 7 lifecycle hooks for memory automation |
117
- | **[Contributing](./CONTRIBUTING.md)** | Bug reports, feature requests, and forking guide |
118
- | **[Security](./SECURITY.md)** | Security model and vulnerability reporting |
119
- | **[Changelog](./CHANGELOG.md)** | Version history |
120
-
121
- **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.
122
-
123
- ## Quick Start
124
-
125
- ### Prerequisites
126
-
127
- - Node.js 22.5+ (for built-in `node:sqlite`)
128
-
129
- No Docker, no API keys, no external services required.
130
-
131
- <details>
132
- <summary><strong>Optional: Build tools for terminal features</strong></summary>
133
-
134
- 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.
135
-
136
- | Platform | Install |
137
- |----------|---------|
138
- | macOS | `xcode-select --install` |
139
- | Linux | `sudo apt install build-essential python3` |
140
- | Windows | [VS Build Tools 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++" |
141
-
142
- </details>
143
-
144
- ### Install via npm
145
-
146
- ```bash
147
- npm install -g synabun
148
- synabun
149
- ```
150
-
151
- ### Or clone from GitHub
152
-
153
- ```bash
154
- git clone --depth=1 https://github.com/danilokhury/Synabun.git
155
- cd Synabun
156
- npm start
157
- ```
158
-
159
- Either method will:
160
- 1. Check prerequisites (Node.js 22.5+)
161
- 2. Install all dependencies
162
- 3. Build the MCP server
163
- 4. Create the SQLite database (`data/memory.db`)
164
- 5. Download the embedding model (~23MB, cached permanently)
165
- 6. Launch the Neural Interface
166
- 7. Open the onboarding wizard in your browser
167
-
168
- <details>
169
- <summary><strong>Manual setup (advanced)</strong></summary>
170
-
171
- ### 1. Build the MCP server
172
-
173
- ```bash
174
- cd mcp-server
175
- npm install
176
- npm run build
177
- ```
178
-
179
- > **Note:** Always use `npm run build` (not `npx tsc`) — npx can install an unrelated `tsc` package instead of using the local TypeScript compiler.
180
-
181
- ### 2. Register with your AI tool
182
-
183
- Add to your project's `.mcp.json`:
184
-
185
- ```json
186
- {
187
- "mcpServers": {
188
- "SynaBun": {
189
- "command": "node",
190
- "args": ["/path/to/Synabun/mcp-server/run.mjs"]
191
- }
192
- }
193
- }
194
- ```
195
-
196
- Or register globally for all projects:
197
-
198
- ```bash
199
- claude mcp add SynaBun node "/path/to/Synabun/mcp-server/run.mjs" -s user
200
- ```
201
-
202
- No environment variables needed — SQLite and local embeddings work out of the box.
203
-
204
- ### 3. Verify
205
-
206
- Restart Claude Code, then run `/mcp`. You should see the `SynaBun` server with 106 tools listed.
207
-
208
- </details>
209
-
210
- <details>
211
- <summary><strong>Platform-specific path notes</strong></summary>
212
-
213
- The `.mcp.json` path must match the platform where **Claude Code is running**:
214
-
215
- | Platform | Path format | Example |
216
- |----------|-------------|---------|
217
- | **Windows** | Forward slashes | `D:/Apps/Synabun/mcp-server/run.mjs` |
218
- | **WSL** | Linux mount paths | `/mnt/d/Apps/Synabun/mcp-server/run.mjs` |
219
- | **Linux/macOS** | Native paths | `/home/user/Apps/Synabun/mcp-server/run.mjs` |
220
-
221
- **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.
222
-
223
- </details>
224
-
225
- ## Architecture
226
-
227
- ```
228
- AI Assistant (any project)
229
- │
230
- │ MCP Protocol (stdio or HTTP)
231
- │
232
- ┌───┴──────────────────────────┐
233
- │ SynaBun MCP Server │ Node.js 22.5+ / TypeScript
234
- │ │
235
- │ 106 tools across 12 groups: │
236
- │ Memory (8), Profile (1), │
237
- │ Browser (40), Whiteboard (5)│
238
- │ Cards (5), Discord (8), │
239
- │ Leonardo (5), GSC (30), │
240
- │ Git (1), Loop (1), │
241
- │ TicTacToe (1), Image (1) │
242
- │ │
243
- │ Transformers.js │ Local embeddings
244
- │ all-MiniLM-L6-v2 │ (384 dims, ~23MB model)
245
- │ │
246
- │ node:sqlite │ Built-in SQLite
247
- │ data/memory.db │ (vectors as Float32 BLOBs)
248
- │ │
249
- │ Playwright │ Browser automation
250
- │ (Chromium) │ (persistent sessions)
251
- └──────────────────────────────┘
252
- ```
253
-
254
- Everything runs in a single Node.js process — no external services, no Docker, no API keys.
255
-
256
- ## MCP Tools (106)
257
-
258
- SynaBun exposes 106 tools via the Model Context Protocol, organized into 12 groups:
259
-
260
- ### Memory (8 tools)
261
-
262
- | Tool | Purpose | Key Parameters |
263
- |------|---------|----------------|
264
- | `remember` | Store a new memory | `content`, `category`, `project`, `tags`, `importance`, `subcategory` |
265
- | `recall` | Semantic search across memories | `query`, `category`, `project`, `tags`, `limit`, `min_importance` |
266
- | `reflect` | Update an existing memory | `memory_id` (full UUID), `content`, `importance`, `tags`, `category` |
267
- | `forget` | Soft-delete a memory (moves to trash) | `memory_id` |
268
- | `restore` | Restore a trashed memory | `memory_id` |
269
- | `memories` | List recent memories or get stats | `action` (recent, stats, by-category, by-project) |
270
- | `sync` | Detect stale memories via file hash comparison | `project` (optional filter) |
271
- | `category` | Create, update, delete, or list categories | `action` (create, update, delete, list), `name`, `description`, `parent` |
272
-
273
- ### Profile (1 tool)
274
-
275
- | Tool | Purpose | Key Parameters |
276
- |------|---------|----------------|
277
- | `profile` | Switch tool profiles at runtime — enable or disable whole groups without restarting | `action` (get / set), `name` (preset), `groups` (custom list) |
278
-
279
- Built-in presets include `full` (all 14 groups) and focused modes for memory-only or browser-only workloads.
280
-
281
- ### Browser (40 tools)
282
-
283
- 19 general browser automation tools + 21 social media extraction tools, all powered by Playwright with persistent Chromium sessions. `browser_snapshot` supports multiple modes + viewport filtering, `returnSnapshot` folds actions and observations into one call, and selector auto-heal via `textHint` repairs brittle locators when a site's DOM changes.
284
-
285
- **General automation:**
286
- `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`, `browser_cheatsheet`
287
-
288
- **Social media extraction:**
289
- `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`
290
-
291
- ### Whiteboard (5 tools)
292
-
293
- | Tool | Purpose |
294
- |------|---------|
295
- | `whiteboard_read` | View whiteboard contents |
296
- | `whiteboard_add` | Place new items on the whiteboard |
297
- | `whiteboard_update` | Modify items on the whiteboard |
298
- | `whiteboard_remove` | Delete items from the whiteboard |
299
- | `whiteboard_screenshot` | Capture the whiteboard as an image |
300
-
301
- ### Cards (5 tools)
302
-
303
- | Tool | Purpose |
304
- |------|---------|
305
- | `card_list` | See all open memory cards |
306
- | `card_open` | Open a memory card on screen |
307
- | `card_close` | Dismiss open memory cards |
308
- | `card_update` | Move, resize, pin, or compact cards |
309
- | `card_screenshot` | Capture open cards as an image |
310
-
311
- ### Discord (8 tools)
312
-
313
- | Tool | Purpose |
314
- |------|---------|
315
- | `discord_guild` | Server info, channels, members, roles, audit log |
316
- | `discord_channel` | Create, edit, delete channels and set permissions |
317
- | `discord_role` | Create, edit, delete roles, assign/remove from members |
318
- | `discord_message` | Send, edit, delete, pin, react, bulk delete, list messages |
319
- | `discord_member` | Member info, kick, ban, unban, timeout, nickname |
320
- | `discord_onboarding` | Welcome screen, rules, verification, onboarding prompts |
321
- | `discord_webhook` | Create, edit, delete, list, execute webhooks |
322
- | `discord_thread` | Create, archive, unarchive, lock, delete threads |
323
-
324
- ### Automation (1 tool)
325
-
326
- | Tool | Purpose |
327
- |------|---------|
328
- | `loop` | Run, stop, or check autonomous background tasks |
329
-
330
- ### Leonardo AI (5 tools)
331
-
332
- 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.
333
-
334
- | Tool | Purpose |
335
- |------|---------|
336
- | `leonardo_browser_navigate` | Navigate to specific Leonardo.ai pages (home, library, image editor, video, upscaler, blueprints, realtime canvas, models) |
337
- | `leonardo_browser_generate` | Fill the prompt and click Generate — configure UI settings (model, style, dimensions, motion controls) beforehand using generic browser tools |
338
- | `leonardo_browser_library` | View or search the Leonardo.ai generation library |
339
- | `leonardo_browser_download` | Capture the current Leonardo.ai page as a screenshot to see generation results |
340
- | `leonardo_browser_reference` | Upload and attach a reference image (style / character / content) to the next generation |
341
-
342
- > **Tip:** Use the `/leonardo` skill in Claude Code or Codex 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.
343
-
344
- ### Google Search Console (30 tools)
345
-
346
- Browser-based control of [Google Search Console](https://search.google.com/search-console). No API key — uses the user's authenticated Google session in the SynaBun browser. Locale-tolerant (selectors keyed to URL paths, material-icon ligatures, and aria roles instead of UI strings).
347
-
348
- **Navigation & property**
349
- | Tool | Purpose |
350
- |------|---------|
351
- | `gsc_navigate` | Open any GSC section (overview, performance_search, performance_discover, performance_news, inspect, pages, videos, sitemaps, removals, cwv_mobile, cwv_desktop, https, security, manual_actions, links, achievements, settings, crawl_stats, users, change_address, associations, disavow, shopping, merchant, plus 17 enhancement reports). Preserves active property. |
352
- | `gsc_property` | List, select, read, or add a property (domain or URL-prefix). |
353
-
354
- **URL Inspection**
355
- | Tool | Purpose |
356
- |------|---------|
357
- | `gsc_inspect_url` | Inspect a URL, polls up to 30s for the result panel, returns structured JSON (indexingState, canonicals, lastCrawl, sitemap, robots, enhancements, etc.). |
358
- | `gsc_inspect_test_live` | Click "Test live URL" and poll up to 90s for live test results. |
359
- | `gsc_inspect_request_indexing` | [mutating] Submit URL to Google's indexing queue. |
360
- | `gsc_inspect_view_crawled` | Open the View Crawled Page panel — switch between html / screenshot / http_response / more_info tabs. |
361
-
362
- **Performance**
363
- | Tool | Purpose |
364
- |------|---------|
365
- | `gsc_performance_query` | Query a Performance report — searchType, dateRange (preset or custom), dimension (query/page/country/device/searchAppearance/date), filter chips, comparison toggle. Auto-scrolls grid up to `limit` rows and returns totals + table JSON. |
366
- | `gsc_performance_export` | Trigger the report Export menu (CSV / Excel / Google Sheets). |
367
- | `gsc_performance_chart_screenshot` | Screenshot the current performance chart. |
368
-
369
- **Indexing**
370
- | Tool | Purpose |
371
- |------|---------|
372
- | `gsc_pages_report` | Read the Pages (Coverage) report — totals, per-reason buckets, optional drill-down to URL examples. |
373
- | `gsc_pages_validate_fix` | [mutating] Start a Validate Fix run for a chosen reason bucket. |
374
- | `gsc_videos_report` | Read the Video Indexing report (same shape as `gsc_pages_report`). |
375
- | `gsc_sitemap` | List, submit, delete, or view errors for sitemaps. |
376
- | `gsc_removals` | List or create URL-removal requests (temporary 6-month, outdated content, SafeSearch). |
377
- | `gsc_removals_cancel` | [mutating] Cancel a pending temporary removal. |
378
-
379
- **Experience, Enhancements, Links**
380
- | Tool | Purpose |
381
- |------|---------|
382
- | `gsc_cwv_report` | Core Web Vitals (mobile / desktop) — poor / needs-improvement / good URL counts and per-issue groups. |
383
- | `gsc_https_report` | HTTPS coverage and non-HTTPS URL reasons. |
384
- | `gsc_security_issues` | Read security issues; optionally request a review. |
385
- | `gsc_manual_actions` | Read manual actions; optionally submit a reconsideration request with custom body text. |
386
- | `gsc_enhancements` | Read any structured-data Enhancements report (breadcrumbs, faq, sitelinks, videos, products, recipes, review, events, jobposting, speakable, qa, logos, sitenames, dataset, practice, math, merchant). |
387
- | `gsc_links_report` | Top linked pages / linking sites / linking text / internally linked. Auto-paginates. |
388
- | `gsc_links_export` | Trigger Links report Export menu. |
389
-
390
- **Settings & Management**
391
- | Tool | Purpose |
392
- |------|---------|
393
- | `gsc_settings` | Read settings page (ownership, verification, users); change address. |
394
- | `gsc_crawl_stats` | Crawl Stats — totals (requests, bytes, response time) plus host / response-code / file-type / Googlebot-type breakdowns. |
395
- | `gsc_users` | List, add, remove, change-role for property users. |
396
- | `gsc_associations` | List, add, remove associations (Analytics, Merchant Center, Ads, Play, YouTube, Actions, Chrome Web Store). |
397
- | `gsc_disavow` | [mutating] Download / upload / delete the Disavow Links file. |
398
- | `gsc_shopping` | Read the Shopping / Merchant Listings report. |
399
- | `gsc_extract_table` | Generic GSC grid → JSON extractor when no specific tool covers a panel. |
400
- | `gsc_screenshot` | Full-page screenshot of the active GSC tab. |
401
-
402
- > **Auth:** GSC tools require an authenticated Google session in the SynaBun-managed browser. If a tool detects a redirect to `accounts.google.com`, it returns a clear error so you can sign in once and retry. URL Inspection polling: 30 s default, 90 s for live test (Google's own timeout). Mutating tools are clearly labelled `[mutating]` in their descriptions.
403
-
404
- ### Image (1 tool)
405
-
406
- | Tool | Purpose |
407
- |------|---------|
408
- | `image_staged` | Manage staged images — list the pending upload queue, remove items, or clear the stage. Used alongside the Neural Interface image-upload flow. |
409
-
410
- ## Neural Interface
411
-
412
- SynaBun includes a 3D visualization UI for browsing and managing memories.
413
-
414
- **Start it:**
415
- ```bash
416
- cd neural-interface
417
- npm start
418
- ```
419
-
420
- Then open **http://localhost:3344**
421
-
422
- **What you get:**
423
- - Interactive force-directed graph — memories as nodes, relationships as edges
424
- - Click nodes to inspect, edit, or delete memories
425
- - Semantic search bar (press `/` to focus)
426
- - Category sidebar with filtering, hierarchy editing, and custom logos
427
- - Drag nodes to pin them in 3D space
428
- - Trash management — view, restore, or permanently purge deleted memories
429
- - Memory Sync — detect stale memories whose source files have changed (SHA-256 hash comparison)
430
- - Backup & Restore — export and import database snapshots
431
- - OpenClaw Bridge — overlay OpenClaw workspace memories as read-only ephemeral nodes
432
- - Graphics quality presets (Low, Medium, High, Ultra)
433
- - Onboarding wizard for first-time setup
434
- - Category export — download all memories in a category as Markdown
435
-
436
- 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.
437
-
438
- ### Sidepanels (Claude Code, Codex, OpenCode)
439
-
440
- Three dedicated chat sidepanels dock to the side of your editor and talk to the same memory backend. They share a common visual language and now ship with matching feature parity:
441
-
442
- | Feature | Claude | Codex | OpenCode |
443
- |---------|--------|-------|----------|
444
- | Tool Activity Dock (left-edge log, `Ctrl/Cmd+Shift+A`) | — | — | ✅ |
445
- | TODO Widget slide-out drawer | ✅ | — | — |
446
- | Agents Drawer with per-agent abort + inline step expansion | ✅ | — | ✅ |
447
- | Permission cards with tool-specific context (bash/edit/write/read/webfetch) | ✅ | ✅ | ✅ |
448
- | Plan mode with AskUserQuestion + post-plan action card | ✅ | ✅ | ✅ |
449
- | Session menu, new-session modal (project + branch picker) | ✅ | ✅ | ✅ |
450
- | Multi-CLI Resume with provider picker | ✅ | ✅ | ✅ |
451
- | Context gauge with 1M context activation | ✅ | ✅ | ✅ |
452
- | Collapsible tool cards with lazy body flush | ✅ | ✅ | ✅ |
453
- | Streamed thinking blocks + 30fps throttled rendering | ✅ | ✅ | ✅ |
454
- | Syntax highlighting + file path linkification + copy button | ✅ | ✅ | ✅ |
455
- | `/synabun` + `/leonardo` multi-runtime skills | ✅ | ✅ | ✅ |
456
- | `/synabun changelog` quick skill button | — | — | ✅ |
457
- | Tray pills for minimized sessions | — | — | ✅ |
458
-
459
- ### Automation Studio
460
-
461
- A visual template editor for autonomous loops and agents.
462
-
463
- - **User-created collapsible folders** — drag/drop templates between folders, reorder folders, per-folder icons (including social platform icons) and colors, per-device collapsed state, backup/restore via `loop-folders.json`.
464
- - **Per-template launch defaults** — save CLI / Model / Thinking effort / MCP profile with each template. The launch modal opens pre-filled with the saved choice; users can still override.
465
- - **First-class 4-CLI support** — Claude Code, Codex, Gemini, and OpenCode. Agent mode is Claude-exclusive; loop mode runs on any of the four.
466
- - **Runtime card with native `<select>`** — handles long MCP profile names and model labels without truncation.
467
- - **Context menus + folder popover** — right-click any template to move it; right-click a folder to rename, recolor, collapse, or delete (deletion detaches templates rather than removing them).
468
-
469
- ### MCP Management
470
-
471
- One screen to manage every MCP server you use, synced across every CLI.
472
-
473
- - **Universal Add Form with smart paste** — auto-detects 5 config formats (stdio JSON, HTTP URL, OpenCode TOML, Claude `mcp add` command, plain JSON).
474
- - **Multi-platform sync** — one MCP server entry syncs to Claude Code, Codex, Gemini, and OpenCode with a single click.
475
- - **Centralized env vault** — secure storage for API keys and tokens, reused across servers, with sensitive-value masking in the form.
476
- - **Auto profile registration** — newly added servers are registered with profiles so they can be toggled by group.
477
- - **One-click install from GitHub** — paste a repo URL; SynaBun clones, builds, and registers the server.
478
- - **`data/mcp/` scaffold** — predictable layout for user-installed MCP servers.
479
-
480
- ### Recall Profiles
481
-
482
- Control how much context flows into each `recall`:
483
-
484
- - **4 presets** — Quick (fast, narrow), Balanced (default), Deep (broad context), Custom (fine-tune).
485
- - **6 fine-tune controls** — number of results, similarity threshold, tag filter intensity, session chunk inclusion, importance floor, temporal bias.
486
- - **Impact indicator** — live estimate of tokens per recall, memories reachable, and how much session context will surface.
487
- - **Configurable server-side defaults** — set the "baseline" recall shape globally; every CLI follows it unless overridden.
488
-
489
- ## Usage
490
-
491
- ### Storing memories
492
-
493
- Format content in **Markdown** for readability:
494
-
495
- ```javascript
496
- remember({
497
- content: `## Redis Price Cache Configuration
498
-
499
- **TTL:** 1 hour (3600 seconds)
500
- **Location:** \`orchestratorSingleton.ts\`
501
-
502
- **Note:** Increasing TTL improves performance but delays price updates.`,
503
- category: "project",
504
- importance: 7,
505
- tags: ["redis", "cache", "pricing"],
506
- subcategory: "architecture"
507
- })
508
- ```
509
-
510
- ### Searching memories
511
-
512
- ```javascript
513
- recall({
514
- query: "how does the price caching work",
515
- limit: 5
516
- })
517
- ```
518
-
519
- Results include similarity score, importance, age, and full content. Filter by category, project, tags, or minimum importance.
520
-
521
- ### Browsing and stats
522
-
523
- ```javascript
524
- memories({ action: "stats" }) // Counts by category and project
525
- memories({ action: "recent", limit: 10 }) // Most recent
526
- memories({ action: "by-category", category: "learning" }) // Filter by category
527
- memories({ action: "by-project", project: "myapp" }) // Filter by project
528
- ```
529
-
530
- ### Updating memories
531
-
532
- ```javascript
533
- reflect({
534
- memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2", // Full UUID required
535
- importance: 9,
536
- add_tags: ["critical"]
537
- })
538
- ```
539
-
540
- ### Deleting and restoring memories
541
-
542
- ```javascript
543
- // Soft-delete (moves to trash)
544
- forget({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })
545
-
546
- // Undo — restore from trash
547
- restore({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })
548
- ```
549
-
550
- ### Detecting stale memories
551
-
552
- ```javascript
553
- // Check which memories have outdated file references
554
- sync({ project: "my-project" })
555
- // Returns: list of memories whose related_files have changed since last update
556
- ```
557
-
558
- 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.
559
-
560
- For detailed usage patterns and best practices, see the [Usage Guide](./docs/usage-guide.md).
561
-
562
- ## Memory Categories
563
-
564
- 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).
565
-
566
- ### How Claude Decides Where to Store Memories
567
-
568
- 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.
569
-
570
- ```
571
- You create categories with descriptions
572
- ↓
573
- buildCategoryDescription() assembles them into a hierarchical guide
574
- ↓
575
- The guide is embedded in the MCP tool schema (Zod .describe())
576
- ↓
577
- Claude reads the guide when calling remember/recall/reflect
578
- ↓
579
- Claude picks the category whose description best matches the memory
580
- ```
581
-
582
- 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.
583
-
584
- ### Writing Effective Descriptions
585
-
586
- Descriptions should be **prescriptive rules**, not vague labels:
587
-
588
- | Quality | Example |
589
- |---------|---------|
590
- | Bad | `"Pricing and stores"` |
591
- | Good | `"ONLY for deal/pricing memories: store imports, price comparisons, Gamivo/YuPlay/Steam pricing. Never put project bugs here."` |
592
- | Bad | `"Bug fixes"` |
593
- | Good | `"Bug fixes, root cause analysis, error resolutions. Must be about actual code bugs — not feature requests or ideas."` |
594
-
595
- **Tips:**
596
- - Be explicit about boundaries — say what does NOT belong as much as what does
597
- - Reference other categories by name — "use deals for pricing, use bug-fixes for bugs"
598
- - List concrete examples — "Gamivo, YuPlay, Steam pricing data"
599
- - Keep it under ~200 chars — Claude reads all descriptions at once, brevity helps
600
-
601
- ### Parent Categories
602
-
603
- Parent categories group related children into visual clusters. They affect how Claude sees the hierarchy:
604
-
605
- ```
606
- [criticalpixel] (parent) — All CriticalPixel memories go here
607
- bug-fixes = Bug fixes, root cause analysis, error resolutions for CP code
608
- databases = Database schemas, queries, migrations, Supabase config
609
- deals = ONLY deal/pricing memories: store imports, price comparisons...
610
- memory-system = MCP server architecture, SQLite config, embedding pipeline...
611
- ```
612
-
613
- Create parents via MCP tools:
614
- ```javascript
615
- category_create({ name: "my-project", description: "All memories for my-project" })
616
- category_update({ name: "bug-fixes", parent: "my-project" })
617
- ```
618
-
619
- Or via the Neural Interface sidebar — click the **Parent** button, then drag categories onto it.
620
-
621
- ### Dynamic Schema Refresh
622
-
623
- ```
624
- category_create / category_update / category_delete
625
- → refreshCategorySchemas()
626
- → invalidateCategoryCache()
627
- → tool.update({ paramsSchema: ... })
628
- → SDK sends notifications/tools/list_changed
629
- → Claude re-fetches tool list → sees updated descriptions
630
- ```
631
-
632
- ## Importance Scale
633
-
634
- | Score | Meaning | When to use |
635
- |-------|---------|------------|
636
- | 1-2 | Trivial | Temporary workarounds, minor preferences |
637
- | 3-4 | Low | Common patterns, routine configs |
638
- | 5 | Normal | Standard decisions (default) |
639
- | 6-7 | Significant | Important patterns, non-obvious fixes |
640
- | 8-9 | Critical | Hard-won bug fixes, key architecture decisions |
641
- | 10 | Foundational | Core architecture, security rules, owner preferences |
642
-
643
- Memories with importance **8+** are immune to time-based relevance decay.
644
-
645
- ## How It Works
646
-
647
- ### Embedding and storage
648
-
649
- 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.
650
-
651
- ### Semantic search
652
-
653
- 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:
654
-
655
- - **Time decay** — 90-day half-life (older memories score lower, unless importance >= 8)
656
- - **Project boost** — memories from the current project get a 1.2x score multiplier
657
- - **Access boost** — frequently recalled memories get a small relevance increase
658
-
659
- ### SQLite schema
660
-
661
- 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.
662
-
663
- ### Access tracking
664
-
665
- Every time a memory is returned by `recall`, its `accessed_at` timestamp and `access_count` are updated (fire-and-forget, non-blocking).
666
-
667
- ## Configuration
668
-
669
- ### Environment variables
670
-
671
- SynaBun works with zero configuration by default. All settings are optional:
672
-
673
- ```env
674
- # Optional overrides
675
- SQLITE_DB_PATH=/custom/path/to/memory.db # Default: data/memory.db
676
- MEMORY_DATA_DIR=/custom/data/dir # Default: mcp-server/data/
677
- NEURAL_PORT=3344 # Neural Interface port (default: 3344)
678
- SETUP_COMPLETE=true
679
-
680
- # API keys (optional — only needed for specific integrations)
681
- DISCORD_BOT_TOKEN=your-token-here # Discord server management
682
- ```
683
-
684
- | Variable | Description |
685
- |----------|-------------|
686
- | `SQLITE_DB_PATH` | Path to SQLite database file (default: `data/memory.db`) |
687
- | `MEMORY_DATA_DIR` | Data directory for runtime files (default: `mcp-server/data/`) |
688
- | `NEURAL_PORT` | Neural Interface server port (default: 3344) |
689
- | `DISCORD_BOT_TOKEN` | Discord bot token for server management tools |
690
-
691
- Set these in the `.env` file at the project root, or let SynaBun use the defaults.
692
-
693
- ## Embeddings
694
-
695
- SynaBun uses **local embeddings** via Transformers.js — no API key or internet connection needed (after the initial ~23MB model download).
696
-
697
- | Property | Value |
698
- |----------|-------|
699
- | **Model** | `Xenova/all-MiniLM-L6-v2` |
700
- | **Dimensions** | 384 |
701
- | **Runtime** | ONNX (via `@huggingface/transformers`) |
702
- | **Cache** | `~/.cache/huggingface/` (permanent, auto-downloaded on first use) |
703
- | **Cost** | Free |
704
-
705
- The model runs entirely in-process — no external service calls, no API keys, no network dependency after first download.
706
-
707
- ## Claude Code Hooks
708
-
709
- 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.
710
-
711
- | Hook | Event | Purpose |
712
- |------|-------|---------|
713
- | `session-start.mjs` | `SessionStart` | Greeting, boot sequence, compaction recovery, loop detection, session registration |
714
- | `prompt-submit.mjs` | `UserPromptSubmit` | Tiered recall nudges, loop iteration injection, category tree on first threshold |
715
- | `pre-compact.mjs` | `PreCompact` | Captures session transcript before context compaction for conversation indexing |
716
- | `stop.mjs` | `Stop` | Combined obligations: compaction, loops, task memory, user learning, conversation turns, auto-store, unstored plans |
717
- | `post-remember.mjs` | `PostToolUse` | Tracks edit count and clears enforcement flags when memories are stored. User learning flag management |
718
- | `pre-websearch.mjs` | `PreToolUse` | Blocks WebSearch/WebFetch during active browser sessions to prevent interference |
719
- | `post-plan.mjs` | `PostToolUse` | Auto-stores plans as memories when exiting plan mode |
720
-
721
- **Install via Neural Interface:** Settings > Integrations > Enable (global or per-project).
722
-
723
- For detailed hook documentation, customization options, and custom hook templates, see the [Hooks Guide](./docs/hooks.md).
724
-
725
- ## Skills (Multi-Runtime)
726
-
727
- SynaBun ships slash-command skills that work on both **Claude Code** and **Codex**, and includes a dedicated quick-action button in the **OpenCode** sidepanel.
728
-
729
- ### `/synabun` — Memory Command Hub
730
-
731
- The entry point for all memory-powered capabilities. Type `/synabun` in Claude Code or Codex and an interactive menu appears:
732
-
733
- | Option | What it does |
734
- |--------|-------------|
735
- | **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. |
736
- | **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. |
737
- | **Memory Health** | Quick stats overview and staleness check — total count, category distribution, stale file references. |
738
- | **Search Memories** | Find something specific across your entire memory bank using semantic search. |
739
- | **Changelog** | Show the SynaBun release history and the newest user-facing features. Available as a dedicated quick-action button inside the OpenCode sidepanel. |
740
-
741
- ### `/leonardo` — Master Media Prompter
742
-
743
- Expert-guided AI image and video creation via Leonardo.ai. Runs on both Claude Code and Codex. Supports quick mode for power users and interactive questionnaires for guided creation.
744
-
745
- | Mode | Usage |
746
- |------|-------|
747
- | **Interactive menu** | `/leonardo` — choose between Create Video, Create Image, Quick Generate, or Account Info |
748
- | **Direct routing** | `/leonardo video sunset over ocean` or `/leonardo image cyberpunk portrait` |
749
- | **Quick mode** | `/leonardo quick a cinematic drone shot of a volcano` — skip the questionnaire, use smart defaults |
750
-
751
- 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).
752
-
753
- **Install:** Copy the skills to your global skills directory (Claude Code example below — Codex uses its own skills location, configured by the Neural Interface installer):
754
-
755
- ```bash
756
- # Skills live at:
757
- ~/.claude/skills/synabun/SKILL.md
758
- ~/.claude/skills/leonardo/SKILL.md
759
- ```
760
-
761
- ## CLAUDE.md Integration
762
-
763
- Add this to any project's `CLAUDE.md` to instruct Claude to use memory automatically:
764
-
765
- <details>
766
- <summary><strong>Show CLAUDE.md template</strong></summary>
767
-
768
- ```markdown
769
- ## Persistent Memory
770
-
771
- You have persistent vector memory via the `SynaBun` MCP server (76 tools).
772
- Core memory tools: remember, recall, forget, restore, reflect, memories, sync, category.
773
- Also available: profile (runtime tool-group toggle), browser automation (40 tools incl. browser_cheatsheet), whiteboard (5), cards (5), discord (8), leonardo AI (5), git, loop, tictactoe, image_staged.
774
-
775
- ### Auto-Recall (do this automatically)
776
- - At session start: recall context about the current project
777
- - When user mentions a specific topic: recall what you know
778
- - Before architecture decisions: recall past decisions
779
- - When debugging: recall past similar bugs
780
-
781
- ### Auto-Remember (do this automatically)
782
- - After fixing a hard bug: remember the solution (importance 7+)
783
- - After architecture decisions: remember the decision and why (importance 8+)
784
- - When user says "remember this": importance 8+
785
- - API quirks or gotchas discovered: remember as learning
786
- - Session-ending context: remember ongoing work as conversation
787
-
788
- ### Memory Tool Quirks
789
- - `remember` accepts `tags` and `importance` directly and returns the full UUID.
790
- - `forget` is a soft delete — use `restore` to undo.
791
- - The `reflect` tool's ID parameter is `memory_id` (not `id`). It requires the FULL UUID format.
792
- - Make memory MCP calls sequentially, not in parallel — one failure cascades to all sibling calls in the batch.
793
- ```
794
-
795
- </details>
796
-
797
- ## Multi-Project Support
798
-
799
- 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.
800
-
801
- 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.
802
-
803
- ## Database
804
-
805
- SynaBun stores all data in a single SQLite file (`data/memory.db`). No external database service needed.
806
-
807
- ```bash
808
- # Database location
809
- ls mcp-server/data/memory.db
810
-
811
- # Backup (just copy the file)
812
- cp mcp-server/data/memory.db ~/backups/memory-$(date +%Y%m%d).db
813
- ```
814
-
815
- ### Rebuilding after code changes
816
-
817
- ```bash
818
- cd mcp-server
819
- npm run build
820
- ```
821
-
822
- No need to restart Claude Code — the MCP server is spawned fresh on each session.
823
-
824
- ### Migrating from Qdrant
825
-
826
- If you have an existing Qdrant-based installation, use the migration script:
827
-
828
- ```bash
829
- cd mcp-server
830
- npm run migrate
831
- ```
832
-
833
- This reads all memories from your Qdrant instance, re-embeds them with the local model, and inserts them into the new SQLite database.
834
-
835
- ## Known Limitations
836
-
837
- ### 1. `reflect` requires full UUID
838
-
839
- `remember` returns the full UUID in its output. Use it directly with `reflect`:
840
-
841
- ```
842
- reflect({ memory_id: "8f7cab3b" }) // Bad Request
843
- reflect({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" }) // Works
844
- ```
845
-
846
- For existing memories, use `recall` to get the full UUID.
847
-
848
- ### 2. Parallel tool call failures
849
-
850
- When making parallel MCP tool calls, if one fails, all sibling calls in that batch may fail. Make memory calls sequentially.
851
-
852
- ## Troubleshooting
853
-
854
- <details>
855
- <summary><strong>Common issues and fixes</strong></summary>
856
-
857
- | Symptom | Cause | Fix |
858
- |---------|-------|-----|
859
- | `Cannot find module '.../dist/index.js'` | TypeScript not compiled | `npm run build` inside `mcp-server/` |
860
- | `npx tsc` installs wrong package | npm's `tsc` package shadows TypeScript | Use `npm run build` instead |
861
- | Node resolves path to `J:\mnt\j\...` | WSL path used with Windows Claude Code | Use Windows paths (`J:/...`) |
862
- | `node:sqlite` not found | Node.js version too old | Upgrade to Node.js 22.5+ |
863
- | `remember` fails with type errors | Rare — older MCP SDK serialization | Update MCP SDK, or use `reflect` as fallback |
864
- | `reflect` returns "Bad Request" | Using shortened ID | Use full UUID from `remember` output or `recall` |
865
- | "Sibling tool call errored" | Parallel MCP call batch failure | Make memory calls sequentially |
866
- | Slow first `remember`/`recall` | Embedding model loading on first use | Normal — model loads once per session (~2-3s) |
867
-
868
- </details>
869
-
870
- ## Cost
871
-
872
- **Free.** SynaBun uses local embeddings (Transformers.js) and a local SQLite database. No API calls, no cloud services, no usage-based billing.
873
-
874
- ## File Structure
875
-
876
- ```
877
- Synabun/
878
- ├── LICENSE # Apache 2.0 License
879
- ├── LICENSE-COMMERCIAL.md # Commercial licensing (Open Core model)
880
- ├── CONTRIBUTING.md # Bug reports, feature requests, and forking guide
881
- ├── CHANGELOG.md # Version history
882
- ├── SECURITY.md # Security policy
883
- ├── .env.example # Example environment configuration
884
- ├── .env # API key config (generated by setup wizard, gitignored)
885
- ├── setup.js # One-command setup & launch script
886
- ├── README.md # This file
887
- ├── CLAUDE.md # Claude Code project instructions (gitignored)
888
- ├── public/
889
- │ ├── synabun.png # Logo
890
- │ └── openclaw-logo-text.png # OpenClaw bridge logo
891
- ├── data/ # Runtime data directory
892
- │ ├── memory.db # SQLite database (all memories + vectors)
893
- │ ├── claude-code-projects.json # Tracked project paths with hook status
894
- │ ├── hook-features.json # Hook feature flags (conversationMemory, greeting, userLearning)
895
- │ ├── mcp-api-key.json # API key for HTTP MCP transport
896
- │ ├── pending-compact/ # PreCompact enforcement flags (per session)
897
- │ ├── pending-remember/ # Edit tracking flags (per session)
898
- │ └── precompact/ # Session transcript cache (pre-compaction)
899
- ├── docs/
900
- │ ├── usage-guide.md # Detailed usage patterns & best practices
901
- │ ├── api-reference.md # Neural Interface REST API reference
902
- │ └── hooks.md # Claude Code hook system documentation
903
- ├── skills/
904
- │ ├── synabun/
905
- │ │ ├── SKILL.md # /synabun command hub (entry point)
906
- │ │ └── modules/
907
- │ │ ├── idea.md # Brainstorm Ideas module
908
- │ │ └── audit.md # Audit Memories module
909
- │ └── leonardo/
910
- │ ├── SKILL.md # /leonardo master media prompter
911
- │ └── modules/
912
- │ ├── video-prompter.md # 5-phase video creation questionnaire
913
- │ ├── image-prompter.md # 5-phase image creation questionnaire
914
- │ ├── model-advisor.md # Decision matrices for 30+ models
915
- │ ├── prompt-library.md # Curated prompt templates
916
- │ └── style-guide.md # Style stacking & motion controls
917
- ├── hooks/
918
- │ └── claude-code/
919
- │ ├── session-start.mjs # SessionStart — greeting, boot sequence, compaction recovery, session registration
920
- │ ├── prompt-submit.mjs # UserPromptSubmit — tiered recall nudges, loop iteration injection
921
- │ ├── pre-compact.mjs # PreCompact — transcript capture before compaction
922
- │ ├── stop.mjs # Stop — combined obligations: compaction, loops, task memory, plans
923
- │ ├── post-remember.mjs # PostToolUse — edit tracking, flag clearing, user learning
924
- │ ├── pre-websearch.mjs # PreToolUse — blocks WebSearch during active browser sessions
925
- │ └── post-plan.mjs # PostToolUse — auto-stores plans as memories
926
- ├── memory-seed/ # Bootstrap seed data for new installations
927
- │ ├── README.md
928
- │ ├── architecture/ # 5 architecture overview memories
929
- │ ├── mcp-tools/ # 7 tool documentation memories
930
- │ ├── neural-interface/ # 5 UI/API documentation memories
931
- │ ├── hooks/ # 4 hook documentation memories
932
- │ ├── setup/ # 3 setup/onboarding memories
933
- │ └── development/ # 4 development guide memories
934
- ├── .tests/ # Vitest test suite
935
- │ ├── vitest.config.ts
936
- │ ├── unit/ # Tool-level unit tests (6 files)
937
- │ ├── scenarios/ # Usage pattern + cost benchmark tests (5 files)
938
- │ ├── mocks/ # SQLite/embedding mocks
939
- │ └── utils/ # Test utilities
940
- ├── neural-interface/ # 3D visualization UI (http://localhost:3344)
941
- │ ├── server.js # Express API — 55+ endpoints
942
- │ ├── package.json
943
- │ └── public/
944
- │ ├── index.html # Three.js force-directed 3D graph
945
- │ ├── index2d.html # 2D canvas visualization variant
946
- │ ├── onboarding.html # Setup wizard
947
- │ └── shared/ # Shared CSS/JS assets
948
- └── mcp-server/ # MCP server (Node.js + TypeScript)
949
- ├── package.json
950
- ├── tsconfig.json
951
- ├── run.mjs # Entry wrapper (sets cwd, imports dist/)
952
- ├── data/
953
- │ ├── custom-categories-*.json # Per-connection category definitions
954
- │ └── display-settings.json # MCP response display config
955
- ├── dist/ # Compiled JS (generated by npm run build)
956
- └── src/
957
- ├── index.ts # Tool registration + schema refresh (76 tools)
958
- ├── config.ts # Namespaced env config, project detection
959
- ├── types.ts # MemoryPayload interface (incl. file_checksums)
960
- ├── http.ts # HTTP MCP transport
961
- ├── tui.ts # Terminal UI for interactive management
962
- ├── services/
963
- │ ├── sqlite.ts # SQLite storage layer (vectors as Float32 BLOBs)
964
- │ ├── local-embeddings.ts # Local embedding generation (Transformers.js)
965
- │ ├── categories.ts # Category CRUD, hierarchy, descriptions
966
- │ └── file-checksums.ts # SHA-256 hashing for sync tool
967
- └── tools/
968
- ├── remember.ts # Store a memory
969
- ├── recall.ts # Semantic search with time decay
970
- ├── forget.ts # Soft-delete (moves to trash)
971
- ├── restore.ts # Restore from trash
972
- ├── reflect.ts # Update a memory
973
- ├── memories.ts # List and stats
974
- ├── sync.ts # Stale memory detection via file hashes
975
- ├── category-create.ts # Create category (triggers schema refresh)
976
- ├── category-update.ts # Edit category (triggers schema refresh)
977
- ├── category-delete.ts # Delete category (triggers schema refresh)
978
- ├── category-list.ts # List categories with hierarchy
979
- ├── leonardo.ts # Leonardo.ai tool registration barrel (4 browser-based tools)
980
- └── leonardo-browser-tools.ts # Browser-based generation, library, navigation, download
981
- ```
982
-
983
- ## License
984
-
985
- Licensed under the [Apache License, Version 2.0](./LICENSE).
986
-
987
- 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.
988
-
989
- ## Trademark Notice
990
-
991
- "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.
1
+ <p align="center">
2
+ <img src="public/synabun.png" alt="SynaBun" width="120" />
3
+ </p>
4
+
5
+ <h1 align="center">SynaBun</h1>
6
+
7
+ <p align="center">
8
+ Persistent vector memory for AI assistants — powered by SQLite and local embeddings.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <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>
13
+ <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>
14
+ <a href="./LICENSE"><img src="https://img.shields.io/npm/l/synabun?color=blue" alt="license" /></a>
15
+ <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>
16
+ <a href="https://discord.gg/x6yWqE9GZP"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
17
+ <a href="https://x.com/SynabunAI"><img src="https://img.shields.io/badge/Follow-%40SynabunAI-000000?logo=x&logoColor=white" alt="X / Twitter" /></a>
18
+ <img src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22+" />
19
+ <img src="https://img.shields.io/badge/MCP-Protocol-8B5CF6" alt="MCP Protocol" />
20
+ <img src="https://img.shields.io/badge/SQLite-Database-003B57?logo=sqlite&logoColor=white" alt="SQLite" />
21
+ </p>
22
+
23
+ <p align="center">
24
+ <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>
25
+ </p>
26
+
27
+ ---
28
+
29
+ Any Claude Code, Codex, Gemini, OpenCode, Cursor, Windsurf, or MCP-compatible AI tool can connect to SynaBun and retain knowledge across sessions through [semantic vector search](https://synabun.ai/blog/all-minilm-l6-v2-mcp-vector-memory). Dedicated sidepanels ship for Claude Code, Codex, and OpenCode with tool activity docks, per-agent abort, permission cards, context gauges, and Multi-CLI Resume. Memories are stored in a [local SQLite database](https://synabun.ai/blog/self-hosted-ai-memory-vs-cloud) with built-in vector search — no external services, no API keys, no Docker.
30
+
31
+ ## Features
32
+
33
+ - **Semantic Search** — find memories by meaning, not keywords, using cosine similarity
34
+ - **Recall Profile Presets** — Quick, Balanced, Deep, and Custom profiles with 6 fine-tune controls, an impact indicator (tokens/recall, memories reachable, session context), and configurable server-side defaults
35
+ - **Multi-Project** — single collection serves all projects with automatic project detection and cross-project recall
36
+ - **Smart Relevance** — time decay (90-day half-life), project boost (1.2x), and access frequency scoring
37
+ - **User-Defined Categories** — hierarchical categories with prescriptive routing descriptions; dynamic schema refresh without server restart
38
+ - **Neural Interface** — interactive 3D force-directed graph visualization at `localhost:3344`
39
+ - **[Local Embeddings](https://synabun.ai/blog/all-minilm-l6-v2-mcp-vector-memory)** — built-in Transformers.js (`all-MiniLM-L6-v2`, 384 dims) — no API key or internet needed after first run
40
+ - **Onboarding Wizard** — guided setup through the Neural Interface UI
41
+ - **Trash & Restore** — soft-delete with full restore capability; trash management via Neural Interface
42
+ - **Memory Sync** — SHA-256 file hash tracking detects when related source files change, flagging stale memories
43
+ - **OpenClaw Bridge** — read-only integration overlays OpenClaw workspace memories as ephemeral nodes in the 3D graph
44
+ - **Category Logos** — upload custom logos for parent categories, rendered on sun nodes in the 3D visualization
45
+ - **Backup & Restore** — export and import SQLite database snapshots via the Neural Interface
46
+ - **[Multi-CLI Sidepanels](https://synabun.ai/blog/skinning-claude-code)** — dedicated sidepanels for Claude Code, Codex, and OpenCode with per-agent abort, tool activity docks, permission cards, TODO drawer, context gauge, session menu, new-session modal with project + branch selection, and Multi-CLI Resume with provider picker
47
+ - **Automation Studio** — visual template editor with user-created collapsible folders (drag/drop, icons, colors), per-template launch defaults (CLI / Model / Thinking effort / MCP profile), and first-class 4-CLI support (Claude Code, Codex, Gemini, OpenCode)
48
+ - **Universal MCP Management** — smart-paste add form auto-detects 5 config formats, syncs one MCP server across Claude Code / Codex / Gemini / OpenCode, centralized env vault with sensitive-value masking, auto profile registration, and one-click install from GitHub
49
+ - **Claude Code Hooks** — 7 lifecycle hooks automate memory recall, storage, and session indexing
50
+ - **User Learning** — 5 binding directives that observe user communication patterns, preferences, and behavioral singularity across sessions (Priority 7 nudge, feature flag, threshold controls)
51
+ - **Hybrid Resume Search** — FTS5 + semantic search across saved sessions so old conversations can be resumed across CLIs
52
+ - **Multi-Runtime Skills** — `/synabun` command hub and `/leonardo` media prompter work on both Claude Code and Codex; `/synabun changelog` quick action available from the OpenCode sidepanel
53
+ - **Leonardo AI Integration** — 5 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
54
+ - **Enhanced Browser Tooling** — new `browser_cheatsheet` tool with curated selectors per platform, snapshot modes + viewport filtering, `returnSnapshot` that folds actions and observations into one call, selector auto-heal via `textHint`, and CLI/sidepanel session isolation
55
+ - **YouTube Trailer Autopilot** — end-to-end game trailer pipeline: discover candidates via IGDB + Steam, download MP4s (Steam direct or yt-dlp), and publish to YouTube Studio with metadata, thumbnails, scheduling, and analytics — all via browser automation (bypasses the Data API's unaudited-project private-lock and ~6/day quota)
56
+ - **Modern Code Rendering** — syntax highlighting, file path linkification, language labels, hover-only copy buttons, 30fps throttled streaming, and real-time thinking block streaming across every sidepanel
57
+
58
+ ## Table of Contents
59
+
60
+ - [Quick Start](#quick-start)
61
+ - [Architecture](#architecture)
62
+ - [MCP Tools](#mcp-tools)
63
+ - [Neural Interface](#neural-interface)
64
+ - [Usage](#usage)
65
+ - [Memory Categories](#memory-categories)
66
+ - [Importance Scale](#importance-scale)
67
+ - [How It Works](#how-it-works)
68
+ - [Configuration](#configuration)
69
+ - [Claude Code Hooks](#claude-code-hooks)
70
+ - [Claude Code Skills](#claude-code-skills)
71
+ - [CLAUDE.md Integration](#claudemd-integration)
72
+ - [Multi-Project Support](#multi-project-support)
73
+ - [Known Limitations](#known-limitations)
74
+ - [Troubleshooting](#troubleshooting)
75
+ - [Cost](#cost)
76
+ - [File Structure](#file-structure)
77
+ - [License](#license)
78
+
79
+ ## Documentation
80
+
81
+ | Document | Description |
82
+ |----------|-------------|
83
+ | **[Website Docs](https://synabun.ai/docs)** | Full documentation on synabun.ai |
84
+ | **[README](./README.md)** | Quick start, architecture, configuration |
85
+ | **[Contributing](./CONTRIBUTING.md)** | Bug reports, feature requests, and forking guide |
86
+ | **[Security](./SECURITY.md)** | Security model and vulnerability reporting |
87
+ | **[Changelog](./CHANGELOG.md)** | Version history |
88
+ | **[Blog](https://synabun.ai/blog)** | Development blog — war stories, architecture decisions, benchmarks |
89
+ | **[Compare](https://synabun.ai/compare)** | Feature comparison with other AI memory tools |
90
+
91
+ **Contributions:** We welcome [bug reports and feature requests](https://github.com/danilokhury/Synabun/issues). Pull requests are not accepted. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
92
+
93
+ ## Quick Start
94
+
95
+ ### Prerequisites
96
+
97
+ - Node.js 22.19+ (required by the current runtime dependencies)
98
+
99
+ No Docker, no API keys, no external services required.
100
+
101
+ <details>
102
+ <summary><strong>Optional: Build tools for terminal features</strong></summary>
103
+
104
+ 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.
105
+
106
+ | Platform | Install |
107
+ |----------|---------|
108
+ | macOS | `xcode-select --install` |
109
+ | Linux | `sudo apt install build-essential python3` |
110
+ | Windows | [VS Build Tools 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++" |
111
+
112
+ </details>
113
+
114
+ ### Install via npm
115
+
116
+ ```bash
117
+ npm install -g synabun
118
+ synabun
119
+ ```
120
+
121
+ ### Or clone from GitHub
122
+
123
+ ```bash
124
+ git clone --depth=1 https://github.com/danilokhury/Synabun.git
125
+ cd Synabun
126
+ npm start
127
+ ```
128
+
129
+ Either method will:
130
+ 1. Check prerequisites (Node.js 22.19+)
131
+ 2. Install all dependencies
132
+ 3. Build the MCP server
133
+ 4. Create the SQLite database (`~/.synabun/mcp-data/memory.db`)
134
+ 5. Download the embedding model (~23MB, cached permanently)
135
+ 6. Launch the Neural Interface
136
+ 7. Open the onboarding wizard in your browser
137
+
138
+ <details>
139
+ <summary><strong>Manual setup (advanced)</strong></summary>
140
+
141
+ ### 1. Build the MCP server
142
+
143
+ ```bash
144
+ cd mcp-server
145
+ npm install
146
+ npm run build
147
+ ```
148
+
149
+ > **Note:** Always use `npm run build` (not `npx tsc`) — npx can install an unrelated `tsc` package instead of using the local TypeScript compiler.
150
+
151
+ ### 2. Register with your AI tool
152
+
153
+ Add to your project's `.mcp.json`:
154
+
155
+ ```json
156
+ {
157
+ "mcpServers": {
158
+ "SynaBun": {
159
+ "command": "node",
160
+ "args": ["/path/to/Synabun/mcp-server/run.mjs"]
161
+ }
162
+ }
163
+ }
164
+ ```
165
+
166
+ Or register globally for all projects:
167
+
168
+ ```bash
169
+ claude mcp add SynaBun node "/path/to/Synabun/mcp-server/run.mjs" -s user
170
+ ```
171
+
172
+ No environment variables needed — SQLite and local embeddings work out of the box.
173
+
174
+ ### 3. Verify
175
+
176
+ Restart Claude Code, then run `/mcp`. You should see the `SynaBun` server with all tools listed.
177
+
178
+ </details>
179
+
180
+ <details>
181
+ <summary><strong>Platform-specific path notes</strong></summary>
182
+
183
+ The `.mcp.json` path must match the platform where **Claude Code is running**:
184
+
185
+ | Platform | Path format | Example |
186
+ |----------|-------------|---------|
187
+ | **Windows** | Forward slashes | `D:/Apps/Synabun/mcp-server/run.mjs` |
188
+ | **WSL** | Linux mount paths | `/mnt/d/Apps/Synabun/mcp-server/run.mjs` |
189
+ | **Linux/macOS** | Native paths | `/home/user/Apps/Synabun/mcp-server/run.mjs` |
190
+
191
+ **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.
192
+
193
+ </details>
194
+
195
+ ## Architecture
196
+
197
+ ```
198
+ AI Assistant (any project)
199
+ │
200
+ │ MCP Protocol (stdio or HTTP)
201
+ │
202
+ ┌───┴──────────────────────────┐
203
+ │ SynaBun MCP Server │ Node.js 22.19+ / TypeScript
204
+ │ │
205
+ │ 117 tools across 13 groups: │
206
+ │ Memory (8), Profile (1), │
207
+ │ Browser (40), Whiteboard (5)│
208
+ │ Cards (5), Discord (8), │
209
+ │ Leonardo (5), GSC (30), │
210
+ │ YouTube (11), Git (1), │
211
+ │ Loop (1), TicTacToe (1), │
212
+ │ Image (1) │
213
+ │ │
214
+ │ Transformers.js │ Local embeddings
215
+ │ all-MiniLM-L6-v2 │ (384 dims, ~23MB model)
216
+ │ │
217
+ │ node:sqlite │ Built-in SQLite
218
+ │ ~/.synabun/mcp-data/ │ (vectors as Float32 BLOBs)
219
+ │ memory.db │
220
+ │ │
221
+ │ Playwright │ Browser automation
222
+ │ (Chromium) │ (persistent sessions)
223
+ └──────────────────────────────┘
224
+ ```
225
+
226
+ Everything runs in a single Node.js process — no external services, no Docker, no API keys.
227
+
228
+ ## MCP Tools (117)
229
+
230
+ SynaBun exposes 117 tools via the Model Context Protocol, organized into 13 groups:
231
+
232
+ ### Memory (8 tools)
233
+
234
+ | Tool | Purpose | Key Parameters |
235
+ |------|---------|----------------|
236
+ | `remember` | Store a new memory | `content`, `category`, `project`, `tags`, `importance`, `subcategory` |
237
+ | `recall` | Semantic search across memories | `query`, `category`, `project`, `tags`, `limit`, `min_importance` |
238
+ | `reflect` | Update an existing memory | `memory_id` (full UUID), `content`, `importance`, `tags`, `category` |
239
+ | `forget` | Soft-delete a memory (moves to trash) | `memory_id` |
240
+ | `restore` | Restore a trashed memory | `memory_id` |
241
+ | `memories` | List recent memories or get stats | `action` (recent, stats, by-category, by-project) |
242
+ | `sync` | Detect stale memories via file hash comparison | `project` (optional filter) |
243
+ | `category` | Create, update, delete, or list categories | `action` (create, update, delete, list), `name`, `description`, `parent` |
244
+
245
+ ### Profile (1 tool)
246
+
247
+ | Tool | Purpose | Key Parameters |
248
+ |------|---------|----------------|
249
+ | `profile` | Switch tool profiles at runtime — enable or disable whole groups without restarting | `action` (get / set), `name` (preset), `groups` (custom list) |
250
+
251
+ Built-in presets include `full` (all 14 groups) and focused modes for memory-only or browser-only workloads.
252
+
253
+ ### [Browser (40 tools)](https://synabun.ai/social-media-automation)
254
+
255
+ 19 general browser automation tools + 21 [social media extraction tools](https://synabun.ai/blog/social-media-automation), all powered by Playwright with persistent Chromium sessions. `browser_snapshot` supports multiple modes + viewport filtering, `returnSnapshot` folds actions and observations into one call, and selector auto-heal via `textHint` repairs brittle locators when a site's DOM changes.
256
+
257
+ **General automation:**
258
+ `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`, `browser_cheatsheet`
259
+
260
+ **Social media extraction:**
261
+ `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`
262
+
263
+ ### Whiteboard (5 tools)
264
+
265
+ | Tool | Purpose |
266
+ |------|---------|
267
+ | `whiteboard_read` | View whiteboard contents |
268
+ | `whiteboard_add` | Place new items on the whiteboard |
269
+ | `whiteboard_update` | Modify items on the whiteboard |
270
+ | `whiteboard_remove` | Delete items from the whiteboard |
271
+ | `whiteboard_screenshot` | Capture the whiteboard as an image |
272
+
273
+ ### Cards (5 tools)
274
+
275
+ | Tool | Purpose |
276
+ |------|---------|
277
+ | `card_list` | See all open memory cards |
278
+ | `card_open` | Open a memory card on screen |
279
+ | `card_close` | Dismiss open memory cards |
280
+ | `card_update` | Move, resize, pin, or compact cards |
281
+ | `card_screenshot` | Capture open cards as an image |
282
+
283
+ ### [Discord (8 tools)](https://synabun.ai/blog/discord-automation)
284
+
285
+ | Tool | Purpose |
286
+ |------|---------|
287
+ | `discord_guild` | Server info, channels, members, roles, audit log |
288
+ | `discord_channel` | Create, edit, delete channels and set permissions |
289
+ | `discord_role` | Create, edit, delete roles, assign/remove from members |
290
+ | `discord_message` | Send, edit, delete, pin, react, bulk delete, list messages |
291
+ | `discord_member` | Member info, kick, ban, unban, timeout, nickname |
292
+ | `discord_onboarding` | Welcome screen, rules, verification, onboarding prompts |
293
+ | `discord_webhook` | Create, edit, delete, list, execute webhooks |
294
+ | `discord_thread` | Create, archive, unarchive, lock, delete threads |
295
+
296
+ ### [Automation (1 tool)](https://synabun.ai/blog/loops-and-agents-from-hell)
297
+
298
+ | Tool | Purpose |
299
+ |------|---------|
300
+ | `loop` | Run, stop, or check autonomous background tasks |
301
+
302
+ ### Leonardo AI (5 tools)
303
+
304
+ 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.
305
+
306
+ | Tool | Purpose |
307
+ |------|---------|
308
+ | `leonardo_browser_navigate` | Navigate to specific Leonardo.ai pages (home, library, image editor, video, upscaler, blueprints, realtime canvas, models) |
309
+ | `leonardo_browser_generate` | Fill the prompt and click Generate — configure UI settings (model, style, dimensions, motion controls) beforehand using generic browser tools |
310
+ | `leonardo_browser_library` | View or search the Leonardo.ai generation library |
311
+ | `leonardo_browser_download` | Capture the current Leonardo.ai page as a screenshot to see generation results |
312
+ | `leonardo_browser_reference` | Upload and attach a reference image (style / character / content) to the next generation |
313
+
314
+ > **Tip:** Use the `/leonardo` skill in Claude Code or Codex 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.
315
+
316
+ ### Google Search Console (30 tools)
317
+
318
+ Browser-based control of [Google Search Console](https://search.google.com/search-console). No API key — uses the user's authenticated Google session in the SynaBun browser. Locale-tolerant (selectors keyed to URL paths, material-icon ligatures, and aria roles instead of UI strings).
319
+
320
+ **Navigation & property**
321
+ | Tool | Purpose |
322
+ |------|---------|
323
+ | `gsc_navigate` | Open any GSC section (overview, performance_search, performance_discover, performance_news, inspect, pages, videos, sitemaps, removals, cwv_mobile, cwv_desktop, https, security, manual_actions, links, achievements, settings, crawl_stats, users, change_address, associations, disavow, shopping, merchant, plus 17 enhancement reports). Preserves active property. |
324
+ | `gsc_property` | List, select, read, or add a property (domain or URL-prefix). |
325
+
326
+ **URL Inspection**
327
+ | Tool | Purpose |
328
+ |------|---------|
329
+ | `gsc_inspect_url` | Inspect a URL, polls up to 30s for the result panel, returns structured JSON (indexingState, canonicals, lastCrawl, sitemap, robots, enhancements, etc.). |
330
+ | `gsc_inspect_test_live` | Click "Test live URL" and poll up to 90s for live test results. |
331
+ | `gsc_inspect_request_indexing` | [mutating] Submit URL to Google's indexing queue. |
332
+ | `gsc_inspect_view_crawled` | Open the View Crawled Page panel — switch between html / screenshot / http_response / more_info tabs. |
333
+
334
+ **Performance**
335
+ | Tool | Purpose |
336
+ |------|---------|
337
+ | `gsc_performance_query` | Query a Performance report — searchType, dateRange (preset or custom), dimension (query/page/country/device/searchAppearance/date), filter chips, comparison toggle. Auto-scrolls grid up to `limit` rows and returns totals + table JSON. |
338
+ | `gsc_performance_export` | Trigger the report Export menu (CSV / Excel / Google Sheets). |
339
+ | `gsc_performance_chart_screenshot` | Screenshot the current performance chart. |
340
+
341
+ **Indexing**
342
+ | Tool | Purpose |
343
+ |------|---------|
344
+ | `gsc_pages_report` | Read the Pages (Coverage) report — totals, per-reason buckets, optional drill-down to URL examples. |
345
+ | `gsc_pages_validate_fix` | [mutating] Start a Validate Fix run for a chosen reason bucket. |
346
+ | `gsc_videos_report` | Read the Video Indexing report (same shape as `gsc_pages_report`). |
347
+ | `gsc_sitemap` | List, submit, delete, or view errors for sitemaps. |
348
+ | `gsc_removals` | List or create URL-removal requests (temporary 6-month, outdated content, SafeSearch). |
349
+ | `gsc_removals_cancel` | [mutating] Cancel a pending temporary removal. |
350
+
351
+ **Experience, Enhancements, Links**
352
+ | Tool | Purpose |
353
+ |------|---------|
354
+ | `gsc_cwv_report` | Core Web Vitals (mobile / desktop) — poor / needs-improvement / good URL counts and per-issue groups. |
355
+ | `gsc_https_report` | HTTPS coverage and non-HTTPS URL reasons. |
356
+ | `gsc_security_issues` | Read security issues; optionally request a review. |
357
+ | `gsc_manual_actions` | Read manual actions; optionally submit a reconsideration request with custom body text. |
358
+ | `gsc_enhancements` | Read any structured-data Enhancements report (breadcrumbs, faq, sitelinks, videos, products, recipes, review, events, jobposting, speakable, qa, logos, sitenames, dataset, practice, math, merchant). |
359
+ | `gsc_links_report` | Top linked pages / linking sites / linking text / internally linked. Auto-paginates. |
360
+ | `gsc_links_export` | Trigger Links report Export menu. |
361
+
362
+ **Settings & Management**
363
+ | Tool | Purpose |
364
+ |------|---------|
365
+ | `gsc_settings` | Read settings page (ownership, verification, users); change address. |
366
+ | `gsc_crawl_stats` | Crawl Stats — totals (requests, bytes, response time) plus host / response-code / file-type / Googlebot-type breakdowns. |
367
+ | `gsc_users` | List, add, remove, change-role for property users. |
368
+ | `gsc_associations` | List, add, remove associations (Analytics, Merchant Center, Ads, Play, YouTube, Actions, Chrome Web Store). |
369
+ | `gsc_disavow` | [mutating] Download / upload / delete the Disavow Links file. |
370
+ | `gsc_shopping` | Read the Shopping / Merchant Listings report. |
371
+ | `gsc_extract_table` | Generic GSC grid → JSON extractor when no specific tool covers a panel. |
372
+ | `gsc_screenshot` | Full-page screenshot of the active GSC tab. |
373
+
374
+ > **Auth:** GSC tools require an authenticated Google session in the SynaBun-managed browser. If a tool detects a redirect to `accounts.google.com`, it returns a clear error so you can sign in once and retry. URL Inspection polling: 30 s default, 90 s for live test (Google's own timeout). Mutating tools are clearly labelled `[mutating]` in their descriptions.
375
+
376
+ ### [YouTube Trailer Autopilot (11 tools)](https://synabun.ai/blog/youtube-automation)
377
+
378
+ End-to-end game trailer pipeline — discover, download, publish, and analyze. Browser automation drives YouTube Studio directly via a signed-in Google session to avoid the Data API's unaudited-project private-lock and ~6/day quota. Sourcing (IGDB + Steam) and analytics delegate to the Neural Interface API.
379
+
380
+ **Discovery & Download**
381
+ | Tool | Purpose |
382
+ |------|---------|
383
+ | `youtube_source` | Discover game trailer candidates via IGDB (metadata + Steam appid + YouTube trailer ids) and Steam Storefront (direct MP4 URLs). Supports genre/platform/hype filters and lookback windows. |
384
+ | `youtube_download` | Download a trailer to disk. Prefers Steam publisher MP4s (direct HTTPS, no yt-dlp/ffmpeg needed); falls back to yt-dlp for YouTube-only trailers. |
385
+
386
+ **Studio Publishing**
387
+ | Tool | Purpose |
388
+ |------|---------|
389
+ | `youtube_navigate` | Open a YouTube Studio section (dashboard, content, analytics, playlists, comments, subtitles, copyright, earn, customization). Auto-resolves the signed-in channel. |
390
+ | `youtube_upload` | [mutating] Upload a local video to YouTube Studio via the Create → Upload dialog. Drives the Polymer/shadow-DOM wizard: title, description, tags, made-for-kids, advances through Details → Video elements → Checks → Visibility, clicks Done. |
391
+ | `youtube_metadata` | [mutating] Edit an existing video's metadata: title, description, tags, category, made-for-kids flag. Saves on completion. |
392
+ | `youtube_thumbnail` | [mutating] Upload a custom thumbnail image to a video via its Studio edit page. |
393
+ | `youtube_schedule` | [mutating] Set a future publish time or immediate visibility via Studio's visibility dialog. Supports ISO or "YYYY-MM-DD HH:MM" format. |
394
+ | `youtube_playlist` | [mutating] Manage playlists — create, add videos, or list existing playlists. |
395
+ | `youtube_endscreen` | [mutating] Apply an end-screen template to a video (default, last_video_subscribe, or import from recent). |
396
+
397
+ **Analytics**
398
+ | Tool | Purpose |
399
+ |------|---------|
400
+ | `youtube_analytics` | Read-only YouTube Analytics via the YouTube Analytics API (OAuth) — views, watch-time, likes, subscribers gained. Channel-wide or per-video. |
401
+ | `youtube_channel` | Channel info or list recent uploads (for deduplication in the autopilot loop). |
402
+
403
+ > **Prerequisites:** IGDB (Twitch) client credentials, Steam API key, YouTube OAuth consent (redirect URI `http://localhost:3344/api/youtube/oauth/callback`), and optionally yt-dlp + ffmpeg for the YouTube fallback download path. Configure in Settings → YouTube. The `youtube` profile preset enables this group alongside git, image, and browser tools.
404
+
405
+ ### Image (1 tool)
406
+
407
+ | Tool | Purpose |
408
+ |------|---------|
409
+ | `image_staged` | Manage staged images — list the pending upload queue, remove items, or clear the stage. Used alongside the Neural Interface image-upload flow. |
410
+
411
+ ## Neural Interface
412
+
413
+ SynaBun includes a 3D visualization UI for browsing and managing memories.
414
+
415
+ **Start it:**
416
+ ```bash
417
+ cd neural-interface
418
+ npm start
419
+ ```
420
+
421
+ Then open **http://localhost:3344**
422
+
423
+ **What you get:**
424
+ - Interactive force-directed graph — memories as nodes, relationships as edges
425
+ - Click nodes to inspect, edit, or delete memories
426
+ - Semantic search bar (press `/` to focus)
427
+ - Category sidebar with filtering, hierarchy editing, and custom logos
428
+ - Drag nodes to pin them in 3D space
429
+ - Trash management — view, restore, or permanently purge deleted memories
430
+ - Memory Sync — detect stale memories whose source files have changed (SHA-256 hash comparison)
431
+ - Backup & Restore — export and import database snapshots
432
+ - OpenClaw Bridge — overlay OpenClaw workspace memories as read-only ephemeral nodes
433
+ - Graphics quality presets (Low, Medium, High, Ultra)
434
+ - Onboarding wizard for first-time setup
435
+ - Category export — download all memories in a category as Markdown
436
+
437
+ 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.
438
+
439
+ ### Sidepanels (Claude Code, Codex, OpenCode)
440
+
441
+ Three dedicated chat sidepanels dock to the side of your editor and talk to the same memory backend. They share a common visual language and now ship with matching feature parity:
442
+
443
+ | Feature | Claude | Codex | OpenCode |
444
+ |---------|--------|-------|----------|
445
+ | Tool Activity Dock (left-edge log, `Ctrl/Cmd+Shift+A`) | — | — | ✅ |
446
+ | TODO Widget slide-out drawer | ✅ | — | — |
447
+ | Agents Drawer with per-agent abort + inline step expansion | ✅ | — | ✅ |
448
+ | Permission cards with tool-specific context (bash/edit/write/read/webfetch) | ✅ | ✅ | ✅ |
449
+ | Plan mode with AskUserQuestion + post-plan action card | ✅ | ✅ | ✅ |
450
+ | Session menu, new-session modal (project + branch picker) | ✅ | ✅ | ✅ |
451
+ | Multi-CLI Resume with provider picker | ✅ | ✅ | ✅ |
452
+ | Context gauge with 1M context activation | ✅ | ✅ | ✅ |
453
+ | Collapsible tool cards with lazy body flush | ✅ | ✅ | ✅ |
454
+ | Streamed thinking blocks + 30fps throttled rendering | ✅ | ✅ | ✅ |
455
+ | Syntax highlighting + file path linkification + copy button | ✅ | ✅ | ✅ |
456
+ | `/synabun` + `/leonardo` multi-runtime skills | ✅ | ✅ | ✅ |
457
+ | `/synabun changelog` quick skill button | — | — | ✅ |
458
+ | Tray pills for minimized sessions | — | — | ✅ |
459
+
460
+ ### Automation Studio
461
+
462
+ A visual template editor for autonomous loops and agents.
463
+
464
+ - **User-created collapsible folders** — drag/drop templates between folders, reorder folders, per-folder icons (including social platform icons) and colors, per-device collapsed state, backup/restore via `loop-folders.json`.
465
+ - **Per-template launch defaults** — save CLI / Model / Thinking effort / MCP profile with each template. The launch modal opens pre-filled with the saved choice; users can still override.
466
+ - **First-class 4-CLI support** — Claude Code, Codex, Gemini, and OpenCode. Agent mode is Claude-exclusive; loop mode runs on any of the four.
467
+ - **Runtime card with native `<select>`** — handles long MCP profile names and model labels without truncation.
468
+ - **Context menus + folder popover** — right-click any template to move it; right-click a folder to rename, recolor, collapse, or delete (deletion detaches templates rather than removing them).
469
+
470
+ ### MCP Management
471
+
472
+ One screen to manage every MCP server you use, synced across every CLI.
473
+
474
+ - **Universal Add Form with smart paste** — auto-detects 5 config formats (stdio JSON, HTTP URL, OpenCode TOML, Claude `mcp add` command, plain JSON).
475
+ - **Multi-platform sync** — one MCP server entry syncs to Claude Code, Codex, Gemini, and OpenCode with a single click.
476
+ - **Centralized env vault** — secure storage for API keys and tokens, reused across servers, with sensitive-value masking in the form.
477
+ - **Auto profile registration** — newly added servers are registered with profiles so they can be toggled by group.
478
+ - **One-click install from GitHub** — paste a repo URL; SynaBun clones, builds, and registers the server.
479
+ - **`data/mcp/` scaffold** — predictable layout for user-installed MCP servers.
480
+
481
+ ### Recall Profiles
482
+
483
+ Control how much context flows into each `recall`:
484
+
485
+ - **4 presets** — Quick (fast, narrow), Balanced (default), Deep (broad context), Custom (fine-tune).
486
+ - **6 fine-tune controls** — number of results, similarity threshold, tag filter intensity, session chunk inclusion, importance floor, temporal bias.
487
+ - **Impact indicator** — live estimate of tokens per recall, memories reachable, and how much session context will surface.
488
+ - **Configurable server-side defaults** — set the "baseline" recall shape globally; every CLI follows it unless overridden.
489
+
490
+ ## Usage
491
+
492
+ ### Storing memories
493
+
494
+ Format content in **Markdown** for readability:
495
+
496
+ ```javascript
497
+ remember({
498
+ content: `## Redis Price Cache Configuration
499
+
500
+ **TTL:** 1 hour (3600 seconds)
501
+ **Location:** \`orchestratorSingleton.ts\`
502
+
503
+ **Note:** Increasing TTL improves performance but delays price updates.`,
504
+ category: "project",
505
+ importance: 7,
506
+ tags: ["redis", "cache", "pricing"],
507
+ subcategory: "architecture"
508
+ })
509
+ ```
510
+
511
+ ### Searching memories
512
+
513
+ ```javascript
514
+ recall({
515
+ query: "how does the price caching work",
516
+ limit: 5
517
+ })
518
+ ```
519
+
520
+ Results include similarity score, importance, age, and full content. Filter by category, project, tags, or minimum importance.
521
+
522
+ ### Browsing and stats
523
+
524
+ ```javascript
525
+ memories({ action: "stats" }) // Counts by category and project
526
+ memories({ action: "recent", limit: 10 }) // Most recent
527
+ memories({ action: "by-category", category: "learning" }) // Filter by category
528
+ memories({ action: "by-project", project: "myapp" }) // Filter by project
529
+ ```
530
+
531
+ ### Updating memories
532
+
533
+ ```javascript
534
+ reflect({
535
+ memory_id: "123e4567-e89b-42d3-a456-426614174000", // Full UUID required
536
+ importance: 9,
537
+ add_tags: ["critical"]
538
+ })
539
+ ```
540
+
541
+ ### Deleting and restoring memories
542
+
543
+ ```javascript
544
+ // Soft-delete (moves to trash)
545
+ forget({ memory_id: "123e4567-e89b-42d3-a456-426614174000" })
546
+
547
+ // Undo — restore from trash
548
+ restore({ memory_id: "123e4567-e89b-42d3-a456-426614174000" })
549
+ ```
550
+
551
+ ### Detecting stale memories
552
+
553
+ ```javascript
554
+ // Check which memories have outdated file references
555
+ sync({ project: "my-project" })
556
+ // Returns: list of memories whose related_files have changed since last update
557
+ ```
558
+
559
+ 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.
560
+
561
+ For detailed usage patterns and best practices, see the [SynaBun documentation](https://synabun.ai/docs).
562
+
563
+ ## Memory Categories
564
+
565
+ Categories are fully user-defined, stored per-connection in `~/.synabun/mcp-data/custom-categories-{connId}.json` by default. There are no hardcoded defaults. Manage them via MCP tools or the [Neural Interface](#neural-interface).
566
+
567
+ ### How Claude Decides Where to Store Memories
568
+
569
+ 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.
570
+
571
+ ```
572
+ You create categories with descriptions
573
+ ↓
574
+ buildCategoryDescription() assembles them into a hierarchical guide
575
+ ↓
576
+ The guide is embedded in the MCP tool schema (Zod .describe())
577
+ ↓
578
+ Claude reads the guide when calling remember/recall/reflect
579
+ ↓
580
+ Claude picks the category whose description best matches the memory
581
+ ```
582
+
583
+ 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.
584
+
585
+ ### Writing Effective Descriptions
586
+
587
+ Descriptions should be **prescriptive rules**, not vague labels:
588
+
589
+ | Quality | Example |
590
+ |---------|---------|
591
+ | Bad | `"Pricing and stores"` |
592
+ | Good | `"ONLY for pricing memories: store imports, price comparisons, and regional pricing. Never put project bugs here."` |
593
+ | Bad | `"Bug fixes"` |
594
+ | Good | `"Bug fixes, root cause analysis, error resolutions. Must be about actual code bugs — not feature requests or ideas."` |
595
+
596
+ **Tips:**
597
+ - Be explicit about boundaries — say what does NOT belong as much as what does
598
+ - Reference other categories by name — "use deals for pricing, use bug-fixes for bugs"
599
+ - List concrete examples — "store imports, regional pricing, discount history"
600
+ - Keep it under ~200 chars — Claude reads all descriptions at once, brevity helps
601
+
602
+ ### Parent Categories
603
+
604
+ Parent categories group related children into visual clusters. They affect how Claude sees the hierarchy:
605
+
606
+ ```
607
+ [my-project] (parent) — All memories for this project go here
608
+ bug-fixes = Bug fixes, root cause analysis, error resolutions for this project
609
+ databases = Database schemas, queries, migrations, Supabase config
610
+ deals = ONLY deal/pricing memories: store imports, price comparisons...
611
+ memory-system = MCP server architecture, SQLite config, embedding pipeline...
612
+ ```
613
+
614
+ Create parents via MCP tools:
615
+ ```javascript
616
+ category_create({ name: "my-project", description: "All memories for my-project" })
617
+ category_update({ name: "bug-fixes", parent: "my-project" })
618
+ ```
619
+
620
+ Or via the Neural Interface sidebar — click the **Parent** button, then drag categories onto it.
621
+
622
+ ### Dynamic Schema Refresh
623
+
624
+ ```
625
+ category_create / category_update / category_delete
626
+ → refreshCategorySchemas()
627
+ → invalidateCategoryCache()
628
+ → tool.update({ paramsSchema: ... })
629
+ → SDK sends notifications/tools/list_changed
630
+ → Claude re-fetches tool list → sees updated descriptions
631
+ ```
632
+
633
+ ## Importance Scale
634
+
635
+ | Score | Meaning | When to use |
636
+ |-------|---------|------------|
637
+ | 1-2 | Trivial | Temporary workarounds, minor preferences |
638
+ | 3-4 | Low | Common patterns, routine configs |
639
+ | 5 | Normal | Standard decisions (default) |
640
+ | 6-7 | Significant | Important patterns, non-obvious fixes |
641
+ | 8-9 | Critical | Hard-won bug fixes, key architecture decisions |
642
+ | 10 | Foundational | Core architecture, security rules, owner preferences |
643
+
644
+ Memories with importance **8+** are immune to time-based relevance decay.
645
+
646
+ ## How It Works
647
+
648
+ ### Embedding and storage
649
+
650
+ 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.
651
+
652
+ ### Semantic search
653
+
654
+ 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:
655
+
656
+ - **Time decay** — 90-day half-life (older memories score lower, unless importance >= 8)
657
+ - **Project boost** — memories from the current project get a 1.2x score multiplier
658
+ - **Access boost** — frequently recalled memories get a small relevance increase
659
+
660
+ ### SQLite schema
661
+
662
+ 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.
663
+
664
+ ### Access tracking
665
+
666
+ Every time a memory is returned by `recall`, its `accessed_at` timestamp and `access_count` are updated (fire-and-forget, non-blocking).
667
+
668
+ ## Configuration
669
+
670
+ ### Environment variables
671
+
672
+ SynaBun works with zero configuration by default. All settings are optional:
673
+
674
+ ```env
675
+ # Optional overrides
676
+ SYNABUN_DATA_HOME=/custom/synabun # Default: ~/.synabun
677
+ SQLITE_DB_PATH=/custom/path/to/memory.db # Default: ~/.synabun/mcp-data/memory.db
678
+ MEMORY_DATA_DIR=/custom/data/dir # Default: ~/.synabun/mcp-data/
679
+ NEURAL_PORT=3344 # Neural Interface port (default: 3344)
680
+ SETUP_COMPLETE=true
681
+
682
+ # API keys (optional — only needed for specific integrations)
683
+ DISCORD_BOT_TOKEN=your-token-here # Discord server management
684
+ ```
685
+
686
+ | Variable | Description |
687
+ |----------|-------------|
688
+ | `SYNABUN_DATA_HOME` | Root for mutable user state (default: `~/.synabun`) |
689
+ | `SQLITE_DB_PATH` | Path to SQLite database file (default: `~/.synabun/mcp-data/memory.db`) |
690
+ | `MEMORY_DATA_DIR` | Data directory for MCP runtime files (default: `~/.synabun/mcp-data/`) |
691
+ | `NEURAL_PORT` | Neural Interface server port (default: 3344) |
692
+ | `DISCORD_BOT_TOKEN` | Discord bot token for server management tools |
693
+
694
+ Set these in `~/.synabun/.env`, or let SynaBun use the defaults. Existing in-repository installs can preview and apply a safe move with `synabun migrate-data` and `synabun migrate-data --apply`.
695
+
696
+ ### Updating safely
697
+
698
+ - **NPM:** `npm install -g synabun@latest` keeps user state outside the package. The in-app updater creates a verified pre-update snapshot before replacing code; a manual NPM update performs the same first-launch verification when `synabun` starts.
699
+ - **Git:** run `git pull --ff-only`, then launch `synabun` once. First launch migrates checkout-local state before normal startup. Do not run `git clean -fdx` until that launch has completed.
700
+ - **Conflicting roots:** SynaBun never merges two populated roots automatically. Run `synabun doctor`, then choose explicitly with `synabun migrate-data --choose external` or `synabun migrate-data --choose legacy`. Both copies are preserved before the choice is activated.
701
+
702
+ Scheduled backups are immutable timestamped ZIP files with manifest checksums and a consistent SQLite snapshot. The default retention keeps every backup for 24 hours, one per day for 30 days, and one per week for 12 weeks, capped at 10 GB. The former `synabun-auto-backup.zip` is recognized as a pinned legacy snapshot and is never automatically deleted.
703
+
704
+ ## Embeddings
705
+
706
+ SynaBun uses **local embeddings** via Transformers.js — no API key or internet connection needed (after the initial ~23MB model download). See [why we chose local over cloud](https://synabun.ai/blog/self-hosted-ai-memory-vs-cloud) and the [all-MiniLM-L6-v2 deep dive](https://synabun.ai/blog/all-minilm-l6-v2-mcp-vector-memory).
707
+
708
+ | Property | Value |
709
+ |----------|-------|
710
+ | **Model** | `Xenova/all-MiniLM-L6-v2` |
711
+ | **Dimensions** | 384 |
712
+ | **Runtime** | ONNX (via `@huggingface/transformers`) |
713
+ | **Cache** | `~/.cache/huggingface/` (permanent, auto-downloaded on first use) |
714
+ | **Cost** | Free |
715
+
716
+ The model runs entirely in-process — no external service calls, no API keys, no network dependency after first download.
717
+
718
+ ## Claude Code Hooks
719
+
720
+ 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.
721
+
722
+ | Hook | Event | Purpose |
723
+ |------|-------|---------|
724
+ | `session-start.mjs` | `SessionStart` | Greeting, boot sequence, compaction recovery, loop detection, session registration |
725
+ | `prompt-submit.mjs` | `UserPromptSubmit` | Tiered recall nudges, loop iteration injection, category tree on first threshold |
726
+ | `pre-compact.mjs` | `PreCompact` | Captures session transcript before context compaction for conversation indexing |
727
+ | `stop.mjs` | `Stop` | Combined obligations: compaction, loops, task memory, user learning, conversation turns, auto-store, unstored plans |
728
+ | `post-remember.mjs` | `PostToolUse` | Tracks edit count and clears enforcement flags when memories are stored. User learning flag management |
729
+ | `pre-websearch.mjs` | `PreToolUse` | Blocks WebSearch/WebFetch during active browser sessions to prevent interference |
730
+ | `post-plan.mjs` | `PostToolUse` | Auto-stores plans as memories when exiting plan mode |
731
+
732
+ **Install via Neural Interface:** Settings > Integrations > Enable (global or per-project).
733
+
734
+ For hook documentation and customization guidance, see the [SynaBun documentation](https://synabun.ai/docs).
735
+
736
+ ## Skills (Multi-Runtime)
737
+
738
+ SynaBun ships slash-command skills that work on both **Claude Code** and **Codex**, and includes a dedicated quick-action button in the **OpenCode** sidepanel.
739
+
740
+ ### `/synabun` — Memory Command Hub
741
+
742
+ The entry point for all memory-powered capabilities. Type `/synabun` in Claude Code or Codex and an interactive menu appears:
743
+
744
+ | Option | What it does |
745
+ |--------|-------------|
746
+ | **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. |
747
+ | **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. |
748
+ | **Memory Health** | Quick stats overview and staleness check — total count, category distribution, stale file references. |
749
+ | **Search Memories** | Find something specific across your entire memory bank using semantic search. |
750
+ | **Changelog** | Show the SynaBun release history and the newest user-facing features. Available as a dedicated quick-action button inside the OpenCode sidepanel. |
751
+
752
+ ### `/leonardo` — Master Media Prompter
753
+
754
+ Expert-guided AI image and video creation via Leonardo.ai. Runs on both Claude Code and Codex. Supports quick mode for power users and interactive questionnaires for guided creation.
755
+
756
+ | Mode | Usage |
757
+ |------|-------|
758
+ | **Interactive menu** | `/leonardo` — choose between Create Video, Create Image, Quick Generate, or Account Info |
759
+ | **Direct routing** | `/leonardo video sunset over ocean` or `/leonardo image cyberpunk portrait` |
760
+ | **Quick mode** | `/leonardo quick a cinematic drone shot of a volcano` — skip the questionnaire, use smart defaults |
761
+
762
+ 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).
763
+
764
+ **Install:** Copy the skills to your global skills directory (Claude Code example below — Codex uses its own skills location, configured by the Neural Interface installer):
765
+
766
+ ```bash
767
+ # Skills live at:
768
+ ~/.claude/skills/synabun/SKILL.md
769
+ ~/.claude/skills/leonardo/SKILL.md
770
+ ```
771
+
772
+ ## CLAUDE.md Integration
773
+
774
+ Add this to any project's `CLAUDE.md` to instruct Claude to use memory automatically:
775
+
776
+ <details>
777
+ <summary><strong>Show CLAUDE.md template</strong></summary>
778
+
779
+ ```markdown
780
+ ## Persistent Memory
781
+
782
+ You have persistent vector memory via the `SynaBun` MCP server (117 tools).
783
+ Core memory tools: remember, recall, forget, restore, reflect, memories, sync, category.
784
+ Also available: profile (runtime tool-group toggle), browser automation (40 tools incl. browser_cheatsheet), whiteboard (5), cards (5), discord (8), leonardo AI (5), YouTube trailer autopilot (11), git, loop, tictactoe, image_staged.
785
+
786
+ ### Auto-Recall (do this automatically)
787
+ - At session start: recall context about the current project
788
+ - When user mentions a specific topic: recall what you know
789
+ - Before architecture decisions: recall past decisions
790
+ - When debugging: recall past similar bugs
791
+
792
+ ### Auto-Remember (do this automatically)
793
+ - After fixing a hard bug: remember the solution (importance 7+)
794
+ - After architecture decisions: remember the decision and why (importance 8+)
795
+ - When user says "remember this": importance 8+
796
+ - API quirks or gotchas discovered: remember as learning
797
+ - Session-ending context: remember ongoing work as conversation
798
+
799
+ ### Memory Tool Quirks
800
+ - `remember` accepts `tags` and `importance` directly and returns the full UUID.
801
+ - `forget` is a soft delete — use `restore` to undo.
802
+ - The `reflect` tool's ID parameter is `memory_id` (not `id`). It requires the FULL UUID format.
803
+ - Make memory MCP calls sequentially, not in parallel — one failure cascades to all sibling calls in the batch.
804
+ ```
805
+
806
+ </details>
807
+
808
+ ## Multi-Project Support
809
+
810
+ 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.
811
+
812
+ 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.
813
+
814
+ ## Database
815
+
816
+ SynaBun stores memories in a single SQLite file (`~/.synabun/mcp-data/memory.db` by default). No external database service is needed.
817
+
818
+ ```bash
819
+ # Database location
820
+ ls ~/.synabun/mcp-data/memory.db
821
+
822
+ # Inspect database, migration, client-registration, and backup health
823
+ synabun doctor
824
+ ```
825
+
826
+ Use **Settings → Auto Backup** or the manual system backup action for a WAL-consistent, checksum-verified backup. Copying `memory.db` while SynaBun is running can omit uncheckpointed WAL data.
827
+
828
+ ### Rebuilding after code changes
829
+
830
+ ```bash
831
+ cd mcp-server
832
+ npm run build
833
+ ```
834
+
835
+ No need to restart Claude Code — the MCP server is spawned fresh on each session.
836
+
837
+ ### Migrating from Qdrant
838
+
839
+ If you have an existing Qdrant-based installation, use the migration script:
840
+
841
+ ```bash
842
+ cd mcp-server
843
+ npm run migrate
844
+ ```
845
+
846
+ This reads all memories from your Qdrant instance, re-embeds them with the local model, and inserts them into the new SQLite database.
847
+
848
+ ## Known Limitations
849
+
850
+ ### 1. `reflect` requires full UUID
851
+
852
+ `remember` returns the full UUID in its output. Use it directly with `reflect`:
853
+
854
+ ```
855
+ reflect({ memory_id: "8f7cab3b" }) // Bad Request
856
+ reflect({ memory_id: "123e4567-e89b-42d3-a456-426614174000" }) // Works
857
+ ```
858
+
859
+ For existing memories, use `recall` to get the full UUID.
860
+
861
+ ### 2. Parallel tool call failures
862
+
863
+ When making parallel MCP tool calls, if one fails, all sibling calls in that batch may fail. Make memory calls sequentially.
864
+
865
+ ## Troubleshooting
866
+
867
+ <details>
868
+ <summary><strong>Common issues and fixes</strong></summary>
869
+
870
+ | Symptom | Cause | Fix |
871
+ |---------|-------|-----|
872
+ | `Cannot find module '.../dist/index.js'` | TypeScript not compiled | `npm run build` inside `mcp-server/` |
873
+ | `npx tsc` installs wrong package | npm's `tsc` package shadows TypeScript | Use `npm run build` instead |
874
+ | Node resolves path to `J:\mnt\j\...` | WSL path used with Windows Claude Code | Use Windows paths (`J:/...`) |
875
+ | `node:sqlite` not found | Node.js version too old | Upgrade to Node.js 22.19+ |
876
+ | `remember` fails with type errors | Rare — older MCP SDK serialization | Update MCP SDK, or use `reflect` as fallback |
877
+ | `reflect` returns "Bad Request" | Using shortened ID | Use full UUID from `remember` output or `recall` |
878
+ | "Sibling tool call errored" | Parallel MCP call batch failure | Make memory calls sequentially |
879
+ | Slow first `remember`/`recall` | Embedding model loading on first use | Normal — model loads once per session (~2-3s) |
880
+
881
+ </details>
882
+
883
+ ## Cost
884
+
885
+ **Free.** SynaBun uses local embeddings (Transformers.js) and a local SQLite database. No API calls, no cloud services, no usage-based billing.
886
+
887
+ ## File Structure
888
+
889
+ ```
890
+ Synabun/
891
+ ├── bin/ # Command-line entry point
892
+ ├── lib/ # Shared path and configuration helpers
893
+ ├── mcp-server/ # TypeScript MCP server
894
+ │ └── src/ # Tools, services, transports, and types
895
+ ├── neural-interface/ # Local web application and agent sidepanels
896
+ │ ├── lib/ # Server-side modules
897
+ │ ├── public/ # Browser assets
898
+ │ ├── tests/ # Node.js regression tests
899
+ │ └── server.js # Express server
900
+ ├── hooks/claude-code/ # Claude Code lifecycle hooks
901
+ ├── skills/ # Bundled multi-runtime skills
902
+ ├── setup.js # Setup and launch entry point
903
+ └── package.json # npm package manifest
904
+ ```
905
+
906
+ Mutable state is stored outside the checkout by default:
907
+
908
+ ```
909
+ ~/.synabun/
910
+ ├── .env # Local configuration and integration credentials
911
+ ├── data/ # UI state, backups, schedules, and runtime files
912
+ └── mcp-data/
913
+ └── memory.db # Memories and vectors
914
+ ```
915
+
916
+ On Windows, the default is `%APPDATA%\synabun`. Set `SYNABUN_DATA_HOME` to use another location.
917
+
918
+ ## License
919
+
920
+ Licensed under the [Apache License, Version 2.0](./LICENSE).
921
+
922
+ 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.
923
+
924
+ ## Trademark Notice
925
+
926
+ "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.