Skip to content
studoo-appPublic

About

Keep your knowledge base and your project docs in sync.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Markoo

Keep your knowledge base and your project docs in sync.

Markoo is a smart two-way connector between a knowledge base and a local Git repository. Write a note in your knowledge base and it lands in your repo's docs/ with working Markdown links; pull a teammate's change to docs/ and your knowledge base is updated.

Knowledge base tools are supported through adapters. Obsidian is the first one implemented; Logseq, Foam, Dendron and plain Markdown folders are designed to follow. When both sides changed, Markoo merges them like Git does, and only asks you when there is a real conflict.

🇫🇷 Version française

Warning

Keep a backup of your notes, and start on a copy: a mistake in the choice of folders copies a lot of files. The Linux app is new and less tried than the macOS one; Windows only has the command line for now.

Markoo sits between the knowledge base (Obsidian) and the Git repository and syncs both with a 3-way diff / merge

Features

  • Any knowledge base, through adapters: Obsidian and plain Markdown folders today, others later. Each adapter converts its tool's Markdown dialect to standard Markdown and back.
  • Three sync directions per pair: KB → repo, repo → KB, or both ways.
  • Projects: pairs are grouped by project, for example a project's documentation and its skill, and a whole project syncs at once. Each pair has a name you choose and can change at any time ("Technical documentation"), and a stable id that keeps its history and hooks.
  • 3-way merge: changes on both sides are merged line by line against the last synced version. You only decide on real conflicts.
  • No data loss: dry-run before anything is written, atomic writes, backups and a trash folder. Markoo never commits or pushes for you.
  • Obsidian ↔ GitHub conversion (first adapter): [[wikilinks]] become standard Markdown links, attachments are copied to assets/, callouts become GitHub alerts, and Obsidian-only frontmatter is filtered — all reversibly.
  • Rename detection: a moved or renamed note is moved on the other side too, and links pointing to it are updated.
  • Many triggers: time interval, Git hooks (post-merge…), local HTTP API, MCP server for Claude and other AI agents, CLI.
  • Desktop app: menu bar status, pair setup wizard, side-by-side conflict view.
  • Cross-platform: the app runs on macOS (Apple Silicon) and Linux; the command line also runs on Intel Macs and Windows. See supported systems.

interface app

How it works

For every file, Markoo compares three versions: the knowledge base, the repo, and the base — the content at the last successful sync. The base tells which side changed, so Markoo can copy, merge or flag a conflict without guessing.

flowchart LR
    B[("Base<br/>last sync")] --> M{"Compare"}
    V["KB"] --> M
    R["Repo"] --> M
    M -->|one side changed| C["Copy"]
    M -->|both changed, no overlap| F["Merge"]
    M -->|both changed, overlap| K["Conflict: you decide"]
Loading

Details: sync algorithm.

Usage

Get the app or the command line from the releases, or build from source with cargo install --path crates/markoo-cli --locked. The user guide explains the rest.

Supported systems

System Desktop app Command line
macOS 11 or later, Apple Silicon ✅ .dmg ✅
macOS 11 or later, Intel ❌ ✅
Linux x86_64 (glibc 2.35 or later: Ubuntu 22.04, Debian 12 or later) ✅ .AppImage, .deb ✅
Windows 10 or later, x86_64 ❌ ✅

The app includes the command line. Linux on ARM and Windows on ARM have no build; the command line can be built from source there.

markoo pair add clara --project Clara --kb ~/Obsidian/Knowledge/Projects/Clara --kb-type obsidian --repo ~/code/clara/docs --direction both
markoo status
markoo sync --dry-run
markoo hook install --pair clara

Configuration lives in a single markoo.toml, editable by hand or from the app. See configuration.

Tech stack

Rust (Cargo workspace) · Tauri 2 · SQLite · axum · MCP (rmcp)

crates/markoo-core     sync engine (all the logic)
crates/markoo-cli      `markoo` command
crates/markoo-daemon   scheduler + HTTP API + MCP host
crates/markoo-mcp      MCP tools
app/                   Tauri desktop app

Documentation

Start with the user guide. The design documentation is available in English and French: documentation index.

Vision and scope Architecture
Sync algorithm Transformations
Triggers Configuration
Roadmap Configuration UI
Knowledge bases User guide

Contributing

Contributions are welcome. Before contributing:

  • documentation is bilingual: any change in documentation/en/ must be mirrored in documentation/fr/ in the same commit, and vice versa.

License

Licensed under the Apache License, Version 2.0.

About

Keep your knowledge base and your project docs in sync.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages