Erich Blume
ee865e5635
The primary surface begins (tech-spec §8): a Neovim plugin that is a thin
client of the local hephd over its unix-socket JSON-RPC.
- node.resolve {title} → Node|null (heph-core Store + dispatch): exact,
owner-scoped, non-tombstoned alias-then-title match — the same mapping that
materializes wiki links, so follow-link jumps to the node the stored link
points at (never fuzzy search). Unit + rpc_socket integration tests.
- heph.nvim/: vim.uv unix-socket JSON-RPC client (blocking call via vim.wait,
id-demuxed, partial-line buffered, luanil so JSON null → Lua nil; isolated
Sessions for tests). Buffer-backed nodes (heph://node/<id>, acwrite;
BufReadCmd→node.get / BufWriteCmd→node.update, whole-buffer body round-trips
exactly through the CRDT). [[wiki-link]] follow on <CR>. Daily journal.
:Heph command surface + completion.
- Headless e2e (§9): a self-contained busted-style runner (tests/e2e/runner.lua)
— no external plugins, no network, deterministic CI exit codes. Specs: journal
round-trip, follow-link (+ unresolved no-op), link-two-docs/backlink.
`make -C heph.nvim test` builds hephd and runs it.
Docs: heph-nvim reference card, §14 tracker (11a done; 11b/11c/11d queued),
changelog fragment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
7.7 KiB
hephaestus
A personal context management system — a single, self-hosted Rust application that fuses a wiki-style knowledge base (Zettelkasten) with task management. Notes and tasks are first-class, cross-linkable entities in one database, so a task like "Fix the roof leak" stays coupled to the home-repair log and contractor-call notes that give it context.
It is offline-first: fully useful on a laptop with no network, and (when the distributed layer lands) auto-syncing to a central instance hosted in blumeops. The primary surface will be a Neovim plugin (heph.nvim, an obsidian.nvim replacement); a CLI (heph) is the utility/scripting surface.
Why "what is next?" is the flagship. heph is organized around concise, honest answers to recurring questions — above all "what do I do right now?" — built from ~10 years of the owner's lived prioritization discipline: projects-as-contexts; attention colors (white/orange/red/blue, where red = a consequence exists if late, not importance); do-dates, not due-dates (earliest-actionable, never a deadline alarm); and working-set tensions surfaced honestly (no "fake happy", no overwhelm).
See docs/explanation/design.md for the vision and rationale, and docs/reference/tech-spec.md for the implementation-facing specification.
Status
Phase 1 (v1 prototype) — nearly feature-complete on branch feature/v1-prototype. All three runtime modes work, replicas sync through a hub over HTTP, and op exchange is authenticated end-to-end with OIDC (Authentik): the hub verifies bearer tokens (JWKS/RS256) and enforces single-tenant ownership, and heph auth login runs the device-code flow, caching tokens in the OS keyring. The offline-first everyday config (local + hub_url) converges with a yrs text-CRDT merging bodies. Remaining: the Neovim plugin (the primary surface). Built test-first (112 tests at last update). The canonical tracker is tech-spec §14.
| Area | State |
|---|---|
| Data model, markdown extraction, wiki-links, export | ✅ done |
| Tasks, links, "what is next?" ranking, recurrence, per-task logs | ✅ done |
hephd daemon — local mode (file lock + JSON-RPC over a unix socket) |
✅ done |
heph CLI; list / health / journal / full-text search (FTS5) |
✅ done |
| Sync engine — HLC, op-log, converging merge + conflict queue (no network yet) | ✅ done |
| yrs text-CRDT for body merge | ✅ done |
server (hub) mode + spoke push/pull sync over HTTP (axum) |
✅ done |
client mode + RemoteStore (online-only, no replica) |
✅ done |
| OIDC hub auth — bearer-token verification + owner gate | ✅ done |
| OIDC client — device-code login, keyring token cache | ✅ done |
heph.nvim (primary surface) — RPC client, buffer-backed editing, wiki-link follow, journal (slice 11a) |
✅ done |
heph.nvim — task/agenda views, promotion, CI runner (slices 11b–11c) |
⏳ next |
Architecture
A Cargo workspace, layered so the same core runs from a laptop to a hub:
crates/heph-core— the library: data model, theStoretrait + SQLite store, markdown parsing/extraction, recurrence, the "what is next?" engine, and the sync engine (op-log, hybrid logical clocks, CRDT/LWW merge, conflict detection). Synchronous and clock-injected (no ambient wall-clock reads) so ranking and merge are deterministic.crates/hephd— the per-device daemon. One binary, three modes —local(own SQLite replica; a syncing spoke when given--hub-url),server(also the sync hub: an HTTP endpoint others sync against),client(thin, remote, no replica — proxies to a--server-url) — selected by configuration via a targetableStorebackend. Surfaces connect to it over a unix socket; it owns the DB handle and background sync.crates/heph— the CLI: a thin client of the daemon (no direct DB access).heph.nvim/(planned) — the Neovim plugin, the primary editing/agenda surface.
Storage: SQLite is the source of truth; a node's body is markdown; export materializes the whole store as a directory of .md files. Sync: each device holds a full replica + an append-only op-log; devices reconcile through a hub with automatic merge (text-CRDT bodies, last-writer-wins scalars, OR-set links) and a conflict queue for the ambiguous remainder. Auth: the hub verifies an OIDC bearer token (Authentik) on every op exchange — RS256/JWKS verification + a single-tenant owner gate — and clients obtain tokens via the OAuth 2.0 device-code flow (heph auth login), cached in the OS keyring. Local-only instances need no auth.
Build & run
Requires a Rust toolchain (stable). The build is a standard Cargo workspace:
cargo build # build all crates
cargo test --all # run the full test suite
cargo clippy --all-targets -- -D warnings
Run the daemon in local mode, then drive it with the CLI:
# Terminal 1 — start the daemon (creates ~/.local/share/heph/heph.db and a socket)
cargo run -p hephd
# Terminal 2 — talk to it
cargo run -p heph -- task "Fix the roof leak" --attention red
cargo run -p heph -- next # the "what is next?" ranking
cargo run -p heph -- doc "Roof log" --body "Called the contractor."
cargo run -p heph -- search roof # full-text search
cargo run -p heph -- journal 2026-06-01 # open/create today's journal
cargo run -p heph -- export ./snapshot # write the store as a .md tree
The daemon takes an exclusive lock on its DB file; --db and --socket override the defaults.
Development
- Test-driven. Every feature has tests at the appropriate layer(s) — unit, property tests, real-socket daemon integration, and CLI process tests. No feature is "done" without them.
- Change process. Changes are classified C0 / C1 / C2 (quick fix / human-review PR / Mikado chain). The v1 prototype is a single long-lived C1. See docs/how-to/agent-change-process.md.
- Git hooks & tooling. prek runs formatting, linting, and secret detection; mise runs repo automation; CI (Forgejo) runs
prekpluscargo fmt/clippy/testvia.forgejo/scripts/build.
prek install && prek install --hook-type commit-msg # set up hooks
prek run --all-files # run all checks
mise tasks # list automation tasks
mise run ai-docs # docs AI agents read first
- Documentation is Diataxis-structured and built with Quartz; changelog fragments use Towncrier under
docs/changelog.d/. Working agents should read AGENTS.md first.
Repository layout
./Cargo.toml # workspace manifest
./crates/heph-core/ # core library: model, store, extraction, recurrence, ranking, sync
./crates/hephd/ # daemon: local/server/client modes — unix-socket RPC + HTTP sync/rpc
./crates/heph/ # CLI: thin client of the daemon
./heph.nvim/ # Neovim plugin (planned)
./docs/ # Diataxis docs (design, tech-spec, how-to), Quartz config
./.forgejo/ # CI build + release workflows and hooks
./.dagger/ # Dagger module backing docs builds/releases
./mise-tasks/ # repo automation via `mise run`
License
All rights reserved. This is a personal, private project — not licensed for use, copying, modification, or distribution. Open-sourcing may be considered in the future. See LICENSE.