https://github.com/ericmann/journal
AI-aware dev journal
https://github.com/ericmann/journal
Last synced: about 12 hours ago
JSON representation
AI-aware dev journal
- Host: GitHub
- URL: https://github.com/ericmann/journal
- Owner: ericmann
- License: mit
- Created: 2026-06-01T15:27:18.000Z (12 days ago)
- Default Branch: main
- Last Pushed: 2026-06-03T20:16:22.000Z (9 days ago)
- Last Synced: 2026-06-05T11:03:01.697Z (8 days ago)
- Language: Go
- Size: 261 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
📓 journal
A local-first developer journal with semantic search and AI synthesis.
Plain-markdown notes in git. Frictionless capture, local RAG retrieval, cloud-Claude synthesis.
---
## What is journal?
`journal` turns a folder of plain-markdown notes into a searchable, AI-queryable
corpus — no server, daemon, or cloud store. Capture is frictionless and
append-only; retrieval is a fully local RAG stack (Ollama embeddings + optional
reranking, vectors in `sqlite-vec`); synthesis is on-demand cloud Claude.
**Markdown in git is the single source of truth** — the vector index is a
disposable, rebuildable cache and is never committed. It all ships as one static
binary.
- 📝 **Frictionless capture** — append a timestamped note inline, in your editor, or from stdin; auto-committed.
- ✅ **Todos that close the loop** — `@todo` in any note becomes a tracked item: `journal todos` lists them, `journal done` checks them off (also via MCP, so Claude can too).
- 🔎 **Local semantic search** — Ollama + `sqlite-vec`, optional LLM reranking; with an API key, a grounded AI answer on top. Notes never leave your machine for retrieval.
- 📺 **A daily home** — `journal today` (day at a glance), `journal tui` (interactive dashboard: notes, todos, search, meetings, stats), `journal stats` (streaks & volume).
- 🤖 **AI synthesis** — daily/weekly rollups and decision digests via cloud Claude, in your own voice.
- 🎙️ **Meeting transcripts** — pull [Quill](https://www.quillmeetings.com) meetings into the same local index (`journal quill-sync`); search, list, and digest them. *(v2.0; Quill is macOS/Windows.)*
- 💾 **Backup & sync** — opt-in `journal sync` keeps a git remote in step, off-machine.
- 🔌 **Integrations** — an MCP server exposes search/recent/decisions/meetings to Claude Desktop and Claude Code.
---
## Requirements
- **git** — notes live in a git repo; capture/index auto-commit.
- **[Ollama](https://ollama.com) + an embedding model** — for indexing and search
(all local). Default: `ollama pull qwen3-embedding:4b`. Verify with `journal doctor`.
- **An Anthropic API key** — *only* for `journal synth`. Set `ANTHROPIC_API_KEY`;
never stored in config. Skip it if you don't synthesize.
- **[Quill](https://www.quillmeetings.com)** *(optional, macOS/Windows)* — only for
`journal quill-sync` to pull meeting transcripts. Everything else works without it.
Capture, the watcher, and backup work without Ollama; only the embedding-backed
features (index, search, synth) need it.
---
## Install
**Homebrew** (macOS) — the cask clears the quarantine flag, so it runs without an
"Allow Anyway" prompt:
```sh
brew install displacetech/tap/journal
```
**Install script** (Linux/macOS) — downloads the latest release, **verifies its
SHA-256**, installs on your `PATH`:
```sh
curl -fsSL https://raw.githubusercontent.com/ericmann/journal/main/install.sh | sh
```
More options — Linux packages, signed archives, build from source
**Linux packages** — each release attaches `.deb`/`.rpm`/`.apk` (amd64/arm64),
with shell completions bundled in:
```sh
sudo dpkg -i journal_*_linux_amd64.deb # Debian/Ubuntu
sudo rpm -i journal_*_linux_amd64.rpm # Fedora/RHEL
sudo apk add --allow-untrusted journal_*_linux_amd64.apk
```
**Direct archive (any platform)** — grab the `tar.gz` from the
[releases page](https://github.com/ericmann/journal/releases) and verify it
against `checksums.txt`, which is [cosign](https://docs.sigstore.dev/)-signed
(keyless):
```sh
cosign verify-blob --signature checksums.txt.sig --certificate checksums.txt.pem \
--certificate-identity-regexp 'https://github.com/ericmann/journal' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
```
**From source** (Go 1.26+):
```sh
git clone https://github.com/ericmann/journal.git && cd journal
make install # build + put a version-stamped static binary on PATH (PREFIX=/usr/local)
```
The install script takes `JOURNAL_VERSION=` to pin and `PREFIX=` to relocate.
Release artifacts are produced by [GoReleaser](https://goreleaser.com) on each
tag; build them locally with `make snapshot`.
Shell completions: package installs wire them up automatically; otherwise
`journal completion bash|zsh|fish` — see [Usage](docs/USAGE.md).
---
## Quick start
```sh
journal init # scaffold a repo in the cwd
ollama pull qwen3-embedding:4b # one-time: the embedding model
journal capture "fallback isn't triggering on OOM #cabot #litellm"
journal capture "declare the dev-fund payment as income" --project canton --marker decision
journal index # embed new notes
journal search "how did we handle the OOM fallback" # ask
```
`journal init` scaffolds:
```
.journal/config.yaml # committed: models, excludes (no secrets)
.journal/index/ # gitignored: the disposable sqlite-vec database
daily/ # the firehose: daily/YYYY/MM/YYYY-MM-DD.md
projects/ # long-lived threads: projects//
reflections/ # synthesis output (drafts)
docs/ # your voice profile + the cron/launchd guide
```
Never commit `.journal/index/` (it's a rebuildable binary blob; `init` gitignores
it). Run `journal doctor` anytime to check Ollama, models, and the index.
---
## Commands
| Command | What it does |
| --- | --- |
| `journal init [path]` | Scaffold (or upgrade) a journal repo |
| `journal capture [text]` | Append a timestamped note (inline / editor / stdin) |
| `journal index [--watch]` | Embed changed notes; `--watch` runs continuously |
| `journal search ` | Semantic search with citations (+ a grounded AI answer when a key is set); `--source notes\|transcript\|all` |
| `journal recent` · `decisions` · `threads` · `meetings` | Metadata views (newest-first, `@decision`, project activity, transcripts) |
| `journal todos` · `journal done ` | List open `@todo` items; check one off (rewrites it to `@done `) |
| `journal today` · `show` · `edit` | Day at a glance; render any note; open a daily file in your editor |
| `journal tui` | Interactive dashboard: today, todos, semantic search, recent, meetings, stats |
| `journal stats` | Capture volume, streaks, marker counts, top tags |
| `journal quill-sync` | Pull Quill meeting transcripts into `transcripts/` ([Quill](docs/QUILL.md)) |
| `journal synth weekly\|daily\|meetings\|decisions\|stale` | AI synthesis via cloud Claude |
| `journal sync` | Back up to / pull from a git remote (opt-in) |
| `journal doctor` | Health-check Ollama, models, the index |
| `journal mcp` | MCP server for Claude Desktop / Claude Code |
Every command takes a global **`--journal-dir`** (or `JOURNAL_DIR` env) to operate
on a journal from any directory — handy for an alias like
`alias jc='journal capture --journal-dir ~/Projects/devnotes'`.
Full flags, the note format, and search internals are in [**Usage**](docs/USAGE.md).
---
## Documentation
| Guide | Contents |
| --- | --- |
| [Usage](docs/USAGE.md) | Capture conventions, command surface, retrieval, the watcher, auto-commit |
| [Meeting transcripts (Quill)](docs/QUILL.md) | Pulling Quill meetings into the index — the v2.0 feature (macOS/Windows) |
| [Configuration](docs/CONFIGURATION.md) | Every `config.yaml` key, defaults, and secrets |
| [Synthesis](docs/SYNTHESIS.md) | `journal synth` and writing in your voice |
| [Remote backup](docs/SYNC.md) | `journal sync`: enabling, conflict modes, cron/launchd/systemd |
| [Workspaces](docs/WORKSPACES.md) | Multiple isolated journals (e.g. personal vs. work) |
| [Integrations](docs/INTEGRATIONS.md) | Claude Desktop, Claude Code, Ollama wiring |
| [Design decisions](docs/DECISIONS.md) | Why the tool is built the way it is |
---
## Development
```sh
make build # go build -o journal .
make test # unit + integration tests (no network; fakes for Ollama/Anthropic)
make lint # gofmt check + go vet (+ golangci-lint if installed)
make snapshot # build the full release artifact set locally (no publish)
```
CI runs build, `gofmt`, `go vet`, race-enabled tests, and `golangci-lint` on every
push and PR. Tests never touch the network — the Ollama and Anthropic clients sit
behind interfaces with deterministic fakes, and integration tests use a temp-file
`sqlite-vec` database.
---
## License
Changes are tracked in [`CHANGELOG.md`](CHANGELOG.md).
MIT © Displace Technologies, LLC ([displace.tech](https://displace.tech)). See
[`LICENSE`](LICENSE). The original technical design and build prompt live in
[`docs/_internal/`](docs/_internal).