Heptabase Local Sync Security

Privacy-first, AI-safe, continuous local sync from Heptabase to structured Markdown.

You decide exactly which cards an AI agent ever gets to see. Everything else stays out of reach.

English · 繁體中文 · 简体中文 · 日本語 · 한국어 · Tiếng Việt · Español · Français · Deutsch · العربية · עברית · Русский · Українська

Unofficial tool. Not affiliated with or endorsed by Heptabase. macOS only for now.

---

Why this exists

It started with a simple goal: connect Heptabase to Claude Code so an AI agent could read my notes.

The official route is Heptabase's own CLI, enabled in the app under Settings, AI Features, CLI. It uses a fail-open mechanism: once you authorize it, the agent can read your entire knowledge base. Third-party tools like the heptabase-mcp server work the same way. That is fine if every card in your knowledge base is safe to share. It does not work if you keep confidential cards next to the ones you want an AI to use, which most people do.

The core issue is that the privacy wall has to sit at the boundary of what the AI can read, and that boundary lives outside Heptabase, in how you feed notes to the agent. The real job of a tool like this is to keep the confidential cards somewhere the AI cannot reach, and export only the rest into AI-readable Markdown. Syncing the notes is the easy half.

The name

The name breaks into three parts, each describing something different. heptabase is the data source, local-sync describes the mechanism, and security defines the role.

Security carries two meanings. The first is protection: the tool stands between the AI and your knowledge base, using a fail-closed mechanism to decide which cards enter the AI's field of view and which are blocked entirely. No data leaks to worry about. The second is closer to a diligent secretary: it quietly organizes your notes in the background, auto-syncing every 15 minutes to wherever you configured, so your AI tools have context ready the moment you open them. Guard the gate and handle the grunt work. That is what the name means.

What it does

Heptabase Local Sync Security runs a local Python script that reads your Heptabase database directly and writes selected cards as Markdown files at destinations you choose. A launchd job runs it every 15 minutes, so the Markdown stays in step with your notes. The AI agent only ever reads the exported Markdown folder and never touches the database.

• Reads the live local database. Heptabase stopped offering automatic local backups in late 2025, so reading the live DB is now the reliable path to continuous local sync.
• Structure-faithful conversion. Tables, bullet / todo / toggle lists, nested sections, and videos are reverse-engineered from Heptabase's ProseMirror schema and rendered as clean Markdown.
• Any-destination routing. Each whiteboard can land in its own folder, including an absolute path that drops a board straight into a separate project. You can collaborate with an AI agent to decide which local path Python should point to.

The fail-closed privacy model

A card is exported only if it matches one of two explicit allow-lists. Nothing is read by default.

Source	Rule
whitelist_whiteboards	Whiteboards you name. Only the cards on each board's surface are read. Sub-whiteboards are not followed. To include one, name it too.
card_map	A title -> exact path layer. These titles are always synced, and their path wins.
blacklist_whiteboards	Cards on these boards are subtracted before any content is read. Blacklist beats whitelist, so a card placed on two boards by mistake is still blocked.
Sub-whiteboards (un-named)	Moving a card into a sub-whiteboard changes its whiteboard_id, so a surface scan never sees it. Excluded by structure, not by a rule you have to remember.

More importantly, every query that touches a card's title or content is constrained to whitelisted whiteboard ids or card_map titles. A non-whitelisted card's title and content are never read into memory at all.

Two design principles follow from this. Structural exclusion beats subtractive exclusion, meaning a card the query cannot reach is safer than one filtered out after reading. The tool is built so you never have to wonder whether a card leaked, guaranteed by structure rather than by checking after the fact.

How it compares

	Heptabase Local Sync Security	Official Heptabase CLI	Other export tools
Privacy model	Fail-closed allow-list	Fail-open (full knowledge base)	Full export
Continuous local sync	Yes (launchd, 15 min)	Read on request	One-shot export
Reads live local DB	Yes	Varies	Often needs a backup file
Structure-faithful Markdown	Tables, lists, sections, video	Varies	Varies
Per-board destination routing	Yes, incl. absolute paths	No	No

This is not a full replacement for Heptabase. "Better than official" holds on three axes only: controllable privacy, continuous local sync, and structure fidelity. The audience is intentionally narrow: macOS users who live in Heptabase and care about what an AI can see. If that is you, this is built for exactly your case.

Install

Requirements: macOS, Python 3.9+, the Heptabase desktop app installed.

git clone https://github.com/yyu0310/heptabase-local-sync-security.git
cd heptabase-local-sync-security
cp config.example.json config.json

Then edit config.json (every field has an inline comment explaining it):

1. Confirm db_path points at your local hepta.db.
2. Set base_output_dir and board_output_dir to where you want Markdown written.
3. List the whiteboards you want to export under whitelist_whiteboards.
4. Add any precise title overrides under card_map.

Run a preview first, which writes nothing:

python3 heptabase_sync.py --dry

When the plan looks right, run it for real:

python3 heptabase_sync.py

Sync automatically every 15 minutes

cp com.example.heptasieve.plist ~/Library/LaunchAgents/
# edit the copied file: set the absolute paths and confirm your python3 path
launchctl load ~/Library/LaunchAgents/com.example.heptasieve.plist

Using it with an AI agent

This tool ships with agent-readable docs so you can set it up by talking to an AI coding agent instead of following steps by hand:

• AGENTS.md and CLAUDE.md tell the agent how to understand and configure this tool.
• llms.txt is a documentation index for LLMs.
• skills/setup-heptasieve/ is a Claude Code skill that walks the whole setup in one request.

Point your agent at the exported Markdown folder, never at hepta.db. That separation is the entire point.

Scenario 1: Claude Code project assistant

You are building a quantitative trading tool. Heptabase has three whiteboards: Trading Strategy Research, System Design Notes, and Personal Financial Records. You add only the first two to whitelist_whiteboards, and the tool syncs them every 15 minutes to /projects/trading/heptabase-export/. You add that folder path to your project's CLAUDE.md so Claude Code reads it as background context. The financial records whiteboard is never in the allowlist; Claude Code cannot see even its title.

Scenario 2: Cross-tool personal memory layer

Different AI tools share no common memory, forcing you to re-explain context every time you switch. Sync your frequently used reference notes, work context, and research summaries to a Markdown folder, and any AI tool that reads local files picks up where you left off in seconds. Which whiteboards enter the allowlist and which stay locked is decided by your config, not by trusting the AI tool's judgment.

How it works

See ARCHITECTURE.md for architecture details, including the data flow, the fail-closed ordering inside build_plan, the database tables it reads, and the privacy invariants to preserve when modifying the code.

Limitations and honest caveats

• Schema is fragile. This depends on Heptabase's internal database shape. A Heptabase update can break it. It is unofficial by nature.
• Reading the live DB is not officially blessed. It works well in practice, and it is read-only, but you should know it is not a supported integration.
• macOS only. The paths and launchd setup assume macOS today.

License

MIT.