Skip to content

Optional Integrations Operator Guide

SecondBrain can use Ollama, n8n, Dify, and plugin-backed connectors such as Microsoft Teams without giving up planning, memory, approvals, tracing, or policy control.

Architecture Summary

  • SecondBrain remains the brain.
  • Ollama is only a provider and embedding backend.
  • n8n is only a governed automation adapter.
  • Dify is only an optional specialized tool adapter.
  • Microsoft 365 uses Microsoft Graph for user-authorized Outlook mail, calendar, OneDrive/SharePoint files, and Teams sync into the local vault.
  • Teams also uses the gateway channel runtime for conversational inbound turns.
  • All approvals, tracing, event logging, retrieval, memory, and decisions stay inside SecondBrain.

What This Is Not

  • n8n is not the orchestrator.
  • Dify is not the brain.
  • Ollama is not the planner.

Current Starter Tools

n8n starter workflows

  • n8n.webhook_ping — read-only health probe, no approval required.
  • n8n.send_summary — side-effectful summary delivery, approval required.
  • n8n.trigger_ingestion — side-effectful ingestion trigger, approval required.

Dify starter apps

  • dify.doc_extract — workflow-style document extraction.
  • dify.qa_assistant — chat-style question answering assistant.

Teams plugin tools

  • teams.profile.get — read the signed-in Microsoft Graph profile.
  • teams.chats.list — list Teams chats.
  • teams.chat.messages.list — read messages from one chat.
  • teams.chat.message.get — fetch one chat message by ID.
  • teams.chat.message.send — post to an existing chat, approval required.
  • teams.channel.messages.list — read messages from one channel.
  • teams.channel.message.get — fetch one channel message by ID.
  • teams.channel.message.reply.send — reply in a channel thread, approval required.
  • teams.planner.task.create / update / delete — Planner writes, approval required.
  • teams.planner.task.details.get / details.update — Planner descriptions, checklists, and references.
  • teams.users.resolve and teams.entities.resolve — resolve routing targets before writes.
  • teams.bot.inbound — gateway channel ingress for Bot Framework message activities.
  • teams.bot.conversation_reference.store — local storage for Bot Framework conversation references.

Microsoft 365 connector sync

  • sb connectors m365-device-login — cache a Microsoft Graph token for Outlook, calendar, files, and Teams reads.
  • sb connectors m365-sync --dry-run --json — preview sync counts before writing anything.
  • sb connectors m365-sync --ingest — write vault artifacts and feed them into the normal ingest/index path.
  • sb connectors m365-sync --source files --download-files --ingest — also store bounded local copies of supported OneDrive files.

Environment Variables

# Ollama
SB_OLLAMA_MODEL="qwen3.5:9b"
SB_OLLAMA_HOST="http://localhost:11434"
# SB_OLLAMA_EMBED_MODEL="nomic-embed-text"

# n8n
# SB_N8N_ENABLED=true
# SB_N8N_BASE_URL=http://localhost:5678
# SB_N8N_API_KEY=your-n8n-api-key
# SB_N8N_TIMEOUT_SECONDS=30
# SB_N8N_MAX_RETRIES=2
# SB_N8N_MCP_SERVER_ID=n8n-mcp
# SB_N8N_INBOUND_ALLOWED_TOOLS=read_file,vault.search

# Dify
# SB_DIFY_ENABLED=true
# SB_DIFY_BASE_URL=http://localhost/v1
# SB_DIFY_API_KEY=app-your-dify-app-key
# SB_DIFY_TIMEOUT=60
# SB_DIFY_MAX_RETRIES=2
# SB_DIFY_APP_DOC_EXTRACT_API_KEY=app-your-doc-extract-key
# SB_DIFY_APP_QA_ASSISTANT_API_KEY=app-your-qa-key

# Teams
# Basic local auth check: az login, then sb teams login
# Manual fallback: sb teams auth
# Env fallback: TEAMS_GRAPH_TOKEN=your-microsoft-graph-access-token
# Conversational ingress: configure channels.teams in ~/.secondbrain/gateway.yaml
# Proactive gateway sends: TEAMS_BOT_APP_ID and TEAMS_BOT_APP_PASSWORD

# Microsoft 365 Graph sync
# M365_GRAPH_CLIENT_ID=your-public-client-app-id
# M365_GRAPH_TOKEN=your-microsoft-graph-access-token

SB_OLLAMA_EMBED_MODEL controls embedding backend selection:

  • set → OllamaEmbeddingBackend
  • unset → MemoryEmbeddingBackend

Local Startup

cp deploy/.env.stack.example .env.stack
make stack-up
make stack-pull-models

sb ollama status
sb n8n status
sb dify status
sb stack check

JSON status is available for smoke tests and operators:

sb ollama status --json
sb n8n status --json
sb dify status --json
sb stack check --json
python scripts/check_stack.py --json

Operator Behavior

Approval behavior

  • n8n.webhook_ping executes directly through ToolExecutor.
  • n8n.send_summary and n8n.trigger_ingestion are classified as destructive in kernel policy and return approval-required unless explicitly approved by the caller.
  • Dify apps stay governed by ToolExecutor and ToolPolicy like any other external tool.

Transport behavior

  • n8n prefers MCP when SB_N8N_MCP_SERVER_ID is configured and the MCP server is healthy.
  • n8n falls back to the HTTP adapter when MCP is missing or unhealthy.
  • Dify uses the HTTP adapter only.

Inbound trust boundaries

  • n8n inbound exposure is deny-by-default.
  • HTTP exposure for n8n-facing tools is controlled by SB_N8N_INBOUND_ALLOWED_TOOLS.
  • The sb serve HTTP surface only exposes allowlisted tools at POST /integrations/n8n/tools/{tool_id}/invoke.
  • MCP exposure for n8n-facing tools depends on RegisteredMCPServer.allowed_tools.
  • If no allowlist is present, no tool is exposed to n8n.

Observability

Every n8n and Dify invocation emits structured audit data through the existing EventLog and trace pipeline.

Tool-call metadata includes:

  • tool name
  • adapter kind
  • trace id and request id
  • side-effect level
  • approval requirement and outcome
  • latency
  • retry count
  • success or failure status

Example CLI Usage

sb n8n registered
sb n8n run webhook_ping --input '{"message":"ping"}'
sb n8n run send_summary --input '{"recipient":"ops@example.com","summary":"Daily digest"}'

sb dify registered
sb dify chat "What changed in the rollout?" --app-id qa_assistant
sb dify workflow doc_extract --input '{"document_text":"Invoice #42"}'

sb plugins show teams
sb plugins status teams
sb plugins validate teams
az login
sb teams login
export TEAMS_GRAPH_CLIENT_ID=<app-client-id>
sb teams device-login
sb teams status
sb teams auth-doctor
sb teams bot-status --json
sb teams bot-manifest --app-id <bot-app-id> --json
sb teams joined-teams --json
sb teams channels <team_id> --json
sb teams channel-messages <team_id> <channel_id> --json
sb teams channel-message <team_id> <channel_id> <message_id> --json
sb teams channel-replies <team_id> <channel_id> <message_id> --json
sb teams chats --json
sb teams chat-message <chat_id> <message_id> --json
sb teams resolve-users "Ada" --json
sb teams planner-plans <team_id> --json
sb teams planner-buckets <plan_id> --json
sb teams planner-tasks <plan_id> --all-pages --json
sb teams planner-task <task_id> --json
sb teams planner-task-details <task_id> --json
sb teams create-planner-task <plan_id> <bucket_id> "Follow up" --dry-run --json
sb teams update-planner-task <task_id> --title "Renamed" --dry-run --json
sb teams update-planner-task-details <task_id> --description "Details" --checklist-item "Call Ada" --dry-run --json
sb teams delete-planner-task <task_id> --dry-run --json
sb connectors m365-device-login
sb connectors m365-sync --dry-run --json
sb connectors m365-sync --source mail --source calendar --ingest
sb connectors m365-sync --source files --download-files --max-file-bytes 2000000 --ingest

Troubleshooting

  • sb ollama status says unreachable: Check that the Ollama daemon is running and SB_OLLAMA_HOST points to it.
  • sb n8n status reports HTTP fallback: The configured MCP server is missing or unhealthy; fix the MCP endpoint or rely on HTTP.
  • sb n8n status reports default deny inbound HTTP: Set SB_N8N_INBOUND_ALLOWED_TOOLS explicitly.
  • sb dify status says auth missing: Set SB_DIFY_API_KEY or the app-scoped SB_DIFY_APP_<APP_ID>_API_KEY.
  • sb teams status says the token is missing: Run az login, run sb teams auth, set TEAMS_GRAPH_TOKEN, or change connectors.teams.token_env.
  • sb teams chats says Microsoft Graph returned 403 Forbidden: The Azure CLI login is valid, but the token lacks Teams Graph permissions. Azure CLI's first-party app cannot request those Teams scopes directly. Use sb teams device-login with an Entra public-client app that has delegated Graph permissions such as User.Read, Chat.ReadBasic, and Chat.ReadWrite.
  • sb teams bot-status says the gateway adapter is not ready: Enable channels.teams in ~/.secondbrain/gateway.yaml and set either a gateway token for local tunnel tests or trusted proxy settings for a verified ingress edge.
  • sb teams bot-status says proactive sends are not ready: Set TEAMS_BOT_APP_ID and TEAMS_BOT_APP_PASSWORD for the Bot Connector app identity used by Azure Bot Service.
  • Azure CLI is unavailable: Set TEAMS_GRAPH_CLIENT_ID or connectors.teams.oauth_client_id, then run sb teams device-login to cache Microsoft identity tokens in the keychain.
  • sb teams update-planner-task or delete-planner-task fails with an ETag error: Re-fetch the task with sb teams planner-task <task_id> --json and retry with the latest @odata.etag, or omit --etag so SecondBrain fetches before writing.
  • sb connectors m365-sync reports Graph 403: The token is valid but lacks the delegated scope required for that source. Re-run sb connectors m365-device-login with the needed scopes or ask the tenant admin to grant consent.
  • OneDrive sync writes only metadata: That is the default. Add --download-files to store bounded local copies of supported file types.
  • Dify output shape is missing vendor fields: That is intentional; only normalized DifyResult fields leave the integration layer.