A calm, local-first personal knowledge workspace combining the structured spatial clarity of Notion with the networked thought of Obsidian.
In Japanese, Kiroku (θ¨ι²) means to chronicle, record, and preserve.
Most modern productivity tools force an uncomfortable compromise:
- Cloud-first database tools (Notion) are structured and visually elegant, but they introduce network latency, vendor lock-in, recurring subscription paywalls, and privacy concerns for sensitive personal thoughts.
- File-over-app tools (Obsidian) provide unmatched privacy and networked linking, but often feel visually spartan, require complex plugin setups, and lack intuitive spatial page nesting.
Kiroku was created as a sanctuary for your thoughts. It unites the warm, tactile clarity of physical stationery with the organic power of bi-directional graph thinking. Everything runs entirely within your browser's IndexedDB engine: zero latency, zero telemetry, zero server dependencies, and instant offline accessibility.
Structured Spatial Clarity (Notion)
+
Organic Networked Thought (Obsidian)
+
Uncompromising Local Privacy (Dexie)
=
θ¨ι² KIROKU
- Direct IndexedDB Persistence: Every page, tag, link, and property is committed locally using Dexie.js. Your thoughts never touch a remote server.
- Immediate Startup: Zero cold boots, zero network lag, and full offline functionality right out of the box.
- Atomic Partial Updates: Writes to note content (
title,content) only patch those specific fields, ensuring concurrent edits to tags, properties, or favorites are never overwritten. - Awaited Navigation Guard: Switching notes, returning to the dashboard, or clicking internal links automatically flushes and awaits persistence before unmounting.
- Sequential Write Serialization: Eliminates race conditions between rapid keystrokes and in-flight database transactions.
- Real-Time Save Indicator: Unobtrusive status feedback:
Saved,Saving...,Unsaved changes, andSave failed β Retry.
- Infinite Page Nesting: Structure notes into parent and sub-pages just like a real notebook or Notion workspace.
- Custom Properties & Metadata: Attach structured key-value pairs (e.g.,
Status,Category,Due Date) to any page. - Curated Visual Accents: Choose from curated emoji icons and understated accent color strips (Slate, Stone, Warm Sand, Terracotta, Sage, Charcoal).
- Instant Wikilinks
[[...]]: Type[[anywhere in the editor to trigger a real-time autocomplete palette for linking documents or creating new ones. - Connected Backlinks: An automatic linked references section at the bottom of each document shows all other pages that reference it, complete with contextual snippets.
- Fleeting Thoughts Queue: A dedicated capture scratchpad on the dashboard lets you jot down ideas, links, or tasks without friction.
- One-Click Promotion: Easily triage inbox items into permanent workspace pages when you are ready to organize.
- Soft Paper (Light Mode): Warm, glare-free
#F4F4F0canvas with#F9F9F5editor cards, subtle dividers, and earthy accentsβcomfortable for hours of deep writing. - True Charcoal Graphite (Dark Mode): Deep
#161719canvas and#222428editor with neutral#32353Cbordersβfree of purple tints, olive casts, or AI-slop gradients. - Reading Typeface Switcher: Toggle instantly between Inter (Sans), Newsreader (Serif), and JetBrains Mono (Monospace).
- Markdown Export: Download any note as a clean
.mddocument with YAML frontmatter. - Bulk Markdown Import: Import folders of Markdown documents with automated
#tagextraction. - Full JSON Snapshot: Export and restore your complete knowledge base with both Merge and Replace modes.
- Fully adaptive interface optimized for smartphones, tablets, laptops, and ultra-wide desktop monitors.
- Touch-friendly tap targets (β₯44px), sliding drawer navigation, and a floating mobile navigation bar.
| Layer | Technology | Rationale |
|---|---|---|
| Framework | React 19 | Concurrent rendering, modern functional components & hooks |
| Language | TypeScript | Strict type safety across data adapters, schemas, and UI |
| Build Tool | Vite 8 | Instantaneous Hot Module Replacement & production tree-shaking |
| Styling | Tailwind CSS v4 | Modern CSS variable tokens, @custom-variant dark, fluid typography |
| Local Database | Dexie.js v4 | High-performance, indexed, transactional wrapper for native IndexedDB |
| Iconography | Lucide React | Consistent, clean stroke icons matching a minimalist visual tone |
Kiroku runs seamlessly across macOS, Linux, and Windows.
Ensure you have Node.js (v18.0.0 or higher; v20 LTS recommended) and npm installed.
Verify your environment:
node --version
npm --version(You can also use pnpm, yarn, or bun if preferred).
-
Clone the repository:
git clone https://github.com/your-username/kiroku.git cd kiroku -
Install dependencies:
npm install
-
Start the development server:
npm run dev
-
Open Kiroku: Navigate to http://localhost:3456 in your web browser.
-
Install Node.js & Git (if needed):
- Ubuntu / Debian:
sudo apt update && sudo apt install -y git nodejs npm - Fedora:
sudo dnf install -y git nodejs npm
- Arch Linux:
sudo pacman -S git nodejs npm
- Ubuntu / Debian:
-
Clone the repository:
git clone https://github.com/your-username/kiroku.git cd kiroku -
Install dependencies:
npm install
-
Launch development server:
npm run dev
-
Open in browser: Open http://localhost:3456.
-
Install Node.js & Git:
- Download the LTS installer from nodejs.org, or install via Windows Package Manager:
winget install OpenJS.NodeJS.LTS winget install Git.Git
- Download the LTS installer from nodejs.org, or install via Windows Package Manager:
-
Clone the repository:
git clone https://github.com/your-username/kiroku.git cd kiroku
-
Install project dependencies:
npm install
-
Start the local server:
npm run dev
-
Open in browser: Navigate to http://localhost:3456.
- Kiroku defaults to unique port
3456with--host=0.0.0.0to avoid conflicts with projects already running on common ports like3000,8080, or Vite's5173. - You can preview the workspace on any other device (like a phone or tablet) connected to your local Wi-Fi network at
http://<your-local-ip>:3456. - To specify a custom port:
npm run dev -- --port 8080
Since Kiroku is 100% local-first, you can inspect your active database in real-time:
- Open Chrome, Edge, Brave, or Firefox Developer Tools (
F12orOption + Cmd + I). - Go to the Application (or Storage) tab.
- Under Storage > IndexedDB, expand
KirokuNotesDB. - You will see two object stores:
pages: Stores documents, titles, markdown content, tags, custom properties, and hierarchies.settings: Stores local user preferences.
Kiroku includes an automated test suite verifying 31 assertions covering race condition prevention, atomic Dexie updates, debounced save flushes, and failure recovery:
npx tsx src/storage/__tests__/saveCoordinator.test.tsTo create an optimized, production-ready static build:
npm run build
npm run previewThe compiled assets will be placed in the dist/ directory, ready to be served by any static host (Cloudflare Pages, Vercel, Netlify, GitHub Pages, or a self-hosted Nginx/Caddy container).
To validate TypeScript types across the entire project:
npm run lintkiroku/
βββ index.html # HTML entry point, typography & dark theme setup
βββ LICENSE # Official MIT License
βββ package.json # Dependencies & project scripts
βββ tsconfig.json # TypeScript compiler configuration
βββ vite.config.ts # Vite bundler configuration
βββ src/
β βββ main.tsx # React DOM mount point
β βββ App.tsx # Root shell and view coordination
β βββ index.css # Tailwind CSS v4 setup & theme design tokens
β βββ types/
β β βββ index.ts # TypeScript definitions (Page, StorageAdapter, etc.)
β βββ storage/
β β βββ db.ts # Dexie database instance ('KirokuNotesDB') & seeds
β β βββ adapter.ts # StorageAdapter abstraction & atomic updates
β β βββ saveCoordinator.ts # Autosave engine, revision queue & navigation guard
β β βββ __tests__/ # Automated 31-assertion storage test suite
β βββ context/
β β βββ WorkspaceContext.tsx # Central workspace state & safe navigation coordination
β βββ utils/
β β βββ tagColors.ts # Deterministic pastel color palette generator
β βββ components/
β βββ layout/ # AppShell, TopNav, MobileTabBar
β βββ dashboard/ # WorkspaceDashboard & quick capture scratchpad
β βββ editor/ # NoteEditor & live MarkdownRenderer
β βββ inbox/ # Quick capture triage view
β βββ all-notes/ # Search, sort, and tag filtering view
β βββ search/ # Command Search Modal (Cmd/Ctrl + K)
β βββ settings/ # Data backup & Markdown import/export modal
β βββ trash/ # Soft-deleted document recovery & permanent purge
| Shortcut | Description |
|---|---|
β K / Ctrl + K |
Open global search palette from anywhere |
[[ (inside editor) |
Trigger Obsidian-style internal note link autocomplete |
Esc |
Close any modal, search palette, or popover |
Enter (in search) |
Open highlighted document (or create new note if query has no matches) |
- Zero Tracking: No Google Analytics, no third-party trackers, and no background network telemetry.
- Device-Bound Storage: Your data lives solely inside your browser's local sandbox.
- Portability by Default: You are never locked in. Export your entire workspace anytime as standard Markdown files or an open JSON snapshot.
We welcome contributions from the community! To contribute:
- Fork the repository.
- Create your feature branch:
git checkout -b feature/amazing-feature. - Commit your changes:
git commit -m 'feat: add amazing feature'. - Push to the branch:
git push origin feature/amazing-feature. - Open a Pull Request.
Distributed under the MIT License. See LICENSE for more information.
Crafted with care for calm, focused, and resilient personal thinking.
θ¨ι² Β· Kiroku