onenote-md

Turn Microsoft OneNote notebooks into clean Markdown your AI agents can actually use.

onenote-md exports OneNote notebooks, sections, pages, metadata, and best-effort assets into a stable Markdown directory for tools like OpenClaw, GBrain, and other local-first agent memory systems.

Why

OneNote is useful for capturing years of notes, but AI agents work better with portable, plain-text, file-based context. This project bridges that gap:

OneNote → Microsoft Graph → Markdown tree → GBrain/OpenClaw/agent memory

Status

Prototype, but functional:

• Microsoft Graph delegated device-code auth
• list notebooks, sections, and pages
• export/sync pages to Markdown
• GBrain-friendly output preset
• YAML frontmatter with source IDs, URLs, timestamps, and content hashes
• best-effort image/resource download
• manifest-based incremental sync
• packaged OpenClaw skill wrapper

Quick start

git clone https://github.com/adamdaum/onenote-md.git
cd onenote-md
npm install
npm run build
cp .env.example .env

Set your Microsoft app registration client ID:

export ONENOTE_MD_CLIENT_ID="<application-client-id>"
export ONENOTE_MD_TENANT_ID="common" # optional

Sign in and inspect OneNote:

node dist/cli.js auth login
node dist/cli.js auth status
node dist/cli.js list notebooks

Export everything visible to the signed-in account:

node dist/cli.js sync --out ./exports/onenote --preset gbrain

Import into GBrain if available:

gbrain import ./exports/onenote

Microsoft auth setup

See docs/MICROSOFT_AUTH.md.

Required delegated Microsoft Graph permissions:

• User.Read
• Notes.Read
• offline_access

No client secret is required. This is a public-client CLI using delegated auth.

Common commands

# Local readiness
node dist/cli.js doctor

# Auth
node dist/cli.js auth login
node dist/cli.js auth status
node dist/cli.js auth logout

# Discovery
node dist/cli.js list notebooks
node dist/cli.js list sections --notebook-id "<notebook-id>"
node dist/cli.js list pages --section-id "<section-id>"

# Export/sync
node dist/cli.js sync --out ./exports/onenote --preset gbrain
node dist/cli.js sync --notebook "Personal" --out ./exports/onenote --preset gbrain
node dist/cli.js sync --section-id "<section-id>" --out ./exports/onenote --preset gbrain

# Safe smoke test
node dist/cli.js sync --out ./exports/onenote --preset gbrain --limit 5 --dry-run

# Regenerate unchanged pages after converter changes
node dist/cli.js sync --out ./exports/onenote --preset gbrain --force

# Skip asset download
node dist/cli.js sync --out ./exports/onenote --preset gbrain --no-assets

Output layout

With --preset gbrain:

exports/onenote/
  manifest.json
  sources/
    onenote/
      <notebook>/
        <section>/
          <date-title>.md
          assets/
            ...

Example Markdown frontmatter:

---
type: source_note
source: onenote
notebook: Personal Notes
section: AI Ideas
title: Project Idea
created: '2026-04-01T12:00:00Z'
modified: '2026-04-24T18:00:00Z'
onenote_page_id: ...
onenote_web_url: ...
content_hash: sha256:...
tags:
  - onenote
  - imported
---

See examples/sample-gbrain-export for sanitized example output.

GBrain and OpenClaw

See docs/GBRAIN_OPENCLAW_WORKFLOW.md.

Packaged OpenClaw skill:

dist-skills/onenote-md-ingest.skill

Skill source:

skills/onenote-md-ingest/

Local HTML conversion

For converter development without Microsoft auth:

node dist/cli.js convert fixtures/sample-page.html \
  --title "Project Idea" \
  --notebook "Personal Notes" \
  --section "AI Ideas" \
  --preset gbrain \
  --out ./examples/sample-gbrain-export

Development

npm install
npm run check

npm run check runs TypeScript build and Vitest tests.

Current limitations

• This is not a full OneNote backup/restore tool.
• Asset handling is best-effort and depends on Microsoft Graph resource URLs in returned page HTML.
• Deleted/moved OneNote pages are not pruned from existing exports yet.
• Handwriting/OCR behavior has not been deeply tested.
• GBrain import is documented/wrapped, not embedded as a runtime dependency.

Docs

• docs/PROJECT_BRIEF.md
• docs/RESEARCH_SPIKE_001.md
• docs/MICROSOFT_AUTH.md
• docs/GBRAIN_OPENCLAW_WORKFLOW.md
• docs/RELEASE_CHECKLIST.md

License

MIT © Adam Daum. Built by Adam Daum / Weststack, LLC.