Skip to main content

Personal mode

Personal mode builds a local personal brain wiki in ~/.openwiki/wiki from configured sources such as local repositories, Custom MCP, Gmail, Notion, web search, Hacker News, Slack, and X/Twitter.

openwiki personal
openwiki personal --init
openwiki personal --update
openwiki personal --update "Refresh the wiki from configured connectors"

Personal mode does not enable host shell execution for the agent. To store personal wiki state somewhere other than ~/.openwiki, set OPENWIKI_CONFIG_DIR. See Customize OpenWiki.

First-run onboarding

On first setup, you can:

  • Configure an inference provider, API key, and model
  • Set a LangSmith API key
  • Set up connectors for supported sources
  • Choose a wiki template, customize its scope, and save per-source ingestion notes and schedules

A schedule is an optional cron for a connector source, such as refreshing Gmail or web search on a recurring interval. OpenWiki stores those cron expressions and related setup details in ~/.openwiki/onboarding.json with the rest of onboarding preferences (selected template, connected sources, and per-source ingestion notes). Global personal wiki instructions are saved separately in ~/.openwiki/INSTRUCTIONS.md.

On macOS, OpenWiki can install supported schedules as user LaunchAgents under ~/Library/LaunchAgents/. Those jobs run openwiki --update --print and write logs under ~/.openwiki/logs/.

Connect your sources

In personal mode, OpenWiki ingests knowledge from the tools you already use and synthesizes it into your local wiki under ~/.openwiki/wiki/. First-run onboarding can set up Custom MCP, local git repositories, Notion, Gmail, X/Twitter, web search, Hacker News, and Slack.

During an ingestion run, connector tools write raw data and manifests under ~/.openwiki/connectors/<connector>/raw/, then source-specific agent runs update the wiki from those local files.

Connector secrets are referenced by env var name and stored in ~/.openwiki/.env.

Important

Connector config files should never contain raw secret values.

Built-in sources

SourceCredentialsBehavior
custom-mcpNone required by defaultConnects to any configured HTTP or stdio MCP server and permits only explicitly safe, read-only tools
git-repoLocal pathsReads configured local repository paths and writes compact manifests
xOAuth user-context credentialsHome timeline, user posts, mentions, bookmarks, and list posts via the X API
notionNotion OAuth (hosted MCP)Authenticate through Notion OAuth instead of pasting a Notion token
googleGmail OAuthFetches recent mail via the Gmail API after openwiki auth gmail
web-searchTAVILY_API_KEYUses Tavily through LangChain
hackernewsNonePublic Hacker News feed and search APIs
slackSlack app client credentials + OAuthRequires HTTPS callback setup for OAuth; see Slack OAuth

You can configure the same source more than once. For example, add one web search source for AI research and another for NBA news. OpenWiki stores them as separate instances such as web-search-1 and web-search-2.

Connect a source

For sources that need credentials, authenticate first, then ingest. Sources such as Hacker News and Custom MCP need no auth by default; web search needs TAVILY_API_KEY in ~/.openwiki/.env.

  1. Authenticate the provider

    Run a local browser OAuth flow for providers that require it. OpenWiki saves returned tokens to ~/.openwiki/.env, creates connector config when possible, and discovers MCP tools for MCP-backed providers:

    openwiki auth notion
openwiki auth gmail
openwiki auth x
openwiki auth slack
    • Slack and Gmail require app client credentials to already be set in ~/.openwiki/.env
    • Notion uses dynamic client registration for hosted MCP
    • X uses OAuth 2.0 with PKCE
    • After openwiki auth gmail, the Google connector can ingest Gmail directly with no MCP transport setup

    Advanced retry helpers:

    openwiki auth configure <provider>
openwiki auth tools <provider>

  2. Ingest the source

    Pull raw data into ~/.openwiki/connectors/ and synthesize updates into the personal wiki:

    openwiki ingest all
openwiki ingest web-search
openwiki ingest web-search-2

    You can also refresh from chat or with openwiki personal --update after sources are configured.

Slack OAuth

Slack OAuth can require an HTTPS redirect URL:

openwiki ngrok start
# or with a fixed domain:
openwiki ngrok start https://your-domain.ngrok.app

OpenWiki saves OPENWIKI_HTTPS_OAUTH_REDIRECT_URI and prints the callback URL to register in Slack. X/Twitter and Gmail auth ignore that HTTPS override and keep using the local callback at http://127.0.0.1:53682/callback by default.

Credential storage

OpenWiki stores secrets under:

  • Directory: ~/.openwiki (mode 0o700)
  • File: ~/.openwiki/.env (mode 0o600)

Common connector-related keys include Gmail, Notion, Slack, and X OAuth tokens, plus TAVILY_API_KEY for web search. Optional OAuth callback settings:

  • OPENWIKI_OAUTH_CALLBACK_PORT: local callback port
  • OPENWIKI_HTTPS_OAUTH_REDIRECT_URI: Slack HTTPS callback URL

For model provider credentials, see Model providers.

Manage schedules

On macOS, manage the connector schedules with:

openwiki cron list
openwiki cron pause <source|all>
openwiki cron resume <source|all>
openwiki cron delete <source|all>

cron delete removes the saved schedule for a source from ~/.openwiki/onboarding.json and unloads its LaunchAgent. It does not remove auth, connector config, raw data, or wiki content.

See also