{"id":50592091,"url":"https://github.com/ericmann/journal","last_synced_at":"2026-06-12T20:00:38.702Z","repository":{"id":362139767,"uuid":"1256232866","full_name":"ericmann/journal","owner":"ericmann","description":"AI-aware dev journal","archived":false,"fork":false,"pushed_at":"2026-06-03T20:16:22.000Z","size":267,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T11:03:01.697Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T15:27:18.000Z","updated_at":"2026-06-03T20:14:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ericmann/journal","commit_stats":null,"previous_names":["ericmann/journal"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/ericmann/journal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fjournal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fjournal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fjournal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fjournal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericmann","download_url":"https://codeload.github.com/ericmann/journal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericmann%2Fjournal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34260310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-05T11:02:03.824Z","updated_at":"2026-06-12T20:00:38.693Z","avatar_url":"https://github.com/ericmann.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Drop a logo at docs/journal-logo.png and swap the \u003ch1\u003e below for:\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/journal-logo.png\" alt=\"journal\" width=\"180\" /\u003e\u003c/p\u003e --\u003e\n\n\u003ch1 align=\"center\"\u003e📓 journal\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA local-first developer journal with semantic search and AI synthesis.\u003c/strong\u003e\u003cbr\u003e\n  Plain-markdown notes in git. Frictionless capture, local RAG retrieval, cloud-Claude synthesis.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ericmann/journal/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/ericmann/journal/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ericmann/journal/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/ericmann/journal?sort=semver\" alt=\"Latest release\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go 1.26+\" /\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-green\" alt=\"MIT License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/brew-displacetech%2Ftap-orange\" alt=\"Homebrew tap\" /\u003e\n\u003c/p\u003e\n\n---\n\n## What is journal?\n\n`journal` turns a folder of plain-markdown notes into a searchable, AI-queryable\ncorpus — no server, daemon, or cloud store. Capture is frictionless and\nappend-only; retrieval is a fully local RAG stack (Ollama embeddings + optional\nreranking, vectors in `sqlite-vec`); synthesis is on-demand cloud Claude.\n\n**Markdown in git is the single source of truth** — the vector index is a\ndisposable, rebuildable cache and is never committed. It all ships as one static\nbinary.\n\n- 📝 **Frictionless capture** — append a timestamped note inline, in your editor, or from stdin; auto-committed.\n- ✅ **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).\n- 🔎 **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.\n- 📺 **A daily home** — `journal today` (day at a glance), `journal tui` (interactive dashboard: notes, todos, search, meetings, stats), `journal stats` (streaks \u0026 volume).\n- 🤖 **AI synthesis** — daily/weekly rollups and decision digests via cloud Claude, in your own voice.\n- 🎙️ **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.)*\n- 💾 **Backup \u0026 sync** — opt-in `journal sync` keeps a git remote in step, off-machine.\n- 🔌 **Integrations** — an MCP server exposes search/recent/decisions/meetings to Claude Desktop and Claude Code.\n\n---\n\n## Requirements\n\n- **git** — notes live in a git repo; capture/index auto-commit.\n- **[Ollama](https://ollama.com) + an embedding model** — for indexing and search\n  (all local). Default: `ollama pull qwen3-embedding:4b`. Verify with `journal doctor`.\n- **An Anthropic API key** — *only* for `journal synth`. Set `ANTHROPIC_API_KEY`;\n  never stored in config. Skip it if you don't synthesize.\n- **[Quill](https://www.quillmeetings.com)** *(optional, macOS/Windows)* — only for\n  `journal quill-sync` to pull meeting transcripts. Everything else works without it.\n\nCapture, the watcher, and backup work without Ollama; only the embedding-backed\nfeatures (index, search, synth) need it.\n\n---\n\n## Install\n\n**Homebrew** (macOS) — the cask clears the quarantine flag, so it runs without an\n\"Allow Anyway\" prompt:\n\n```sh\nbrew install displacetech/tap/journal\n```\n\n**Install script** (Linux/macOS) — downloads the latest release, **verifies its\nSHA-256**, installs on your `PATH`:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/ericmann/journal/main/install.sh | sh\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eMore options — Linux packages, signed archives, build from source\u003c/summary\u003e\n\n**Linux packages** — each release attaches `.deb`/`.rpm`/`.apk` (amd64/arm64),\nwith shell completions bundled in:\n\n```sh\nsudo dpkg -i journal_*_linux_amd64.deb     # Debian/Ubuntu\nsudo rpm  -i journal_*_linux_amd64.rpm     # Fedora/RHEL\nsudo apk add --allow-untrusted journal_*_linux_amd64.apk\n```\n\n**Direct archive (any platform)** — grab the `tar.gz` from the\n[releases page](https://github.com/ericmann/journal/releases) and verify it\nagainst `checksums.txt`, which is [cosign](https://docs.sigstore.dev/)-signed\n(keyless):\n\n```sh\ncosign verify-blob --signature checksums.txt.sig --certificate checksums.txt.pem \\\n  --certificate-identity-regexp 'https://github.com/ericmann/journal' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt\n```\n\n**From source** (Go 1.26+):\n\n```sh\ngit clone https://github.com/ericmann/journal.git \u0026\u0026 cd journal\nmake install     # build + put a version-stamped static binary on PATH (PREFIX=/usr/local)\n```\n\nThe install script takes `JOURNAL_VERSION=` to pin and `PREFIX=` to relocate.\nRelease artifacts are produced by [GoReleaser](https://goreleaser.com) on each\ntag; build them locally with `make snapshot`.\n\u003c/details\u003e\n\nShell completions: package installs wire them up automatically; otherwise\n`journal completion bash|zsh|fish` — see [Usage](docs/USAGE.md).\n\n---\n\n## Quick start\n\n```sh\njournal init                                          # scaffold a repo in the cwd\nollama pull qwen3-embedding:4b                         # one-time: the embedding model\njournal capture \"fallback isn't triggering on OOM #cabot #litellm\"\njournal capture \"declare the dev-fund payment as income\" --project canton --marker decision\njournal index                                          # embed new notes\njournal search \"how did we handle the OOM fallback\"    # ask\n```\n\n`journal init` scaffolds:\n\n```\n.journal/config.yaml   # committed: models, excludes (no secrets)\n.journal/index/        # gitignored: the disposable sqlite-vec database\ndaily/                 # the firehose: daily/YYYY/MM/YYYY-MM-DD.md\nprojects/              # long-lived threads: projects/\u003cslug\u003e/\nreflections/           # synthesis output (drafts)\ndocs/                  # your voice profile + the cron/launchd guide\n```\n\nNever commit `.journal/index/` (it's a rebuildable binary blob; `init` gitignores\nit). Run `journal doctor` anytime to check Ollama, models, and the index.\n\n---\n\n## Commands\n\n| Command | What it does |\n| --- | --- |\n| `journal init [path]` | Scaffold (or upgrade) a journal repo |\n| `journal capture [text]` | Append a timestamped note (inline / editor / stdin) |\n| `journal index [--watch]` | Embed changed notes; `--watch` runs continuously |\n| `journal search \u003cquery\u003e` | Semantic search with citations (+ a grounded AI answer when a key is set); `--source notes\\|transcript\\|all` |\n| `journal recent` · `decisions` · `threads` · `meetings` | Metadata views (newest-first, `@decision`, project activity, transcripts) |\n| `journal todos` · `journal done \u003cref\u003e` | List open `@todo` items; check one off (rewrites it to `@done \u003cdate\u003e`) |\n| `journal today` · `show` · `edit` | Day at a glance; render any note; open a daily file in your editor |\n| `journal tui` | Interactive dashboard: today, todos, semantic search, recent, meetings, stats |\n| `journal stats` | Capture volume, streaks, marker counts, top tags |\n| `journal quill-sync` | Pull Quill meeting transcripts into `transcripts/` ([Quill](docs/QUILL.md)) |\n| `journal synth weekly\\|daily\\|meetings\\|decisions\\|stale` | AI synthesis via cloud Claude |\n| `journal sync` | Back up to / pull from a git remote (opt-in) |\n| `journal doctor` | Health-check Ollama, models, the index |\n| `journal mcp` | MCP server for Claude Desktop / Claude Code |\n\nEvery command takes a global **`--journal-dir`** (or `JOURNAL_DIR` env) to operate\non a journal from any directory — handy for an alias like\n`alias jc='journal capture --journal-dir ~/Projects/devnotes'`.\n\nFull flags, the note format, and search internals are in [**Usage**](docs/USAGE.md).\n\n---\n\n## Documentation\n\n| Guide | Contents |\n| --- | --- |\n| [Usage](docs/USAGE.md) | Capture conventions, command surface, retrieval, the watcher, auto-commit |\n| [Meeting transcripts (Quill)](docs/QUILL.md) | Pulling Quill meetings into the index — the v2.0 feature (macOS/Windows) |\n| [Configuration](docs/CONFIGURATION.md) | Every `config.yaml` key, defaults, and secrets |\n| [Synthesis](docs/SYNTHESIS.md) | `journal synth` and writing in your voice |\n| [Remote backup](docs/SYNC.md) | `journal sync`: enabling, conflict modes, cron/launchd/systemd |\n| [Workspaces](docs/WORKSPACES.md) | Multiple isolated journals (e.g. personal vs. work) |\n| [Integrations](docs/INTEGRATIONS.md) | Claude Desktop, Claude Code, Ollama wiring |\n| [Design decisions](docs/DECISIONS.md) | Why the tool is built the way it is |\n\n---\n\n## Development\n\n```sh\nmake build    # go build -o journal .\nmake test     # unit + integration tests (no network; fakes for Ollama/Anthropic)\nmake lint     # gofmt check + go vet (+ golangci-lint if installed)\nmake snapshot # build the full release artifact set locally (no publish)\n```\n\nCI runs build, `gofmt`, `go vet`, race-enabled tests, and `golangci-lint` on every\npush and PR. Tests never touch the network — the Ollama and Anthropic clients sit\nbehind interfaces with deterministic fakes, and integration tests use a temp-file\n`sqlite-vec` database.\n\n---\n\n## License\n\nChanges are tracked in [`CHANGELOG.md`](CHANGELOG.md).\n\nMIT © Displace Technologies, LLC ([displace.tech](https://displace.tech)). See\n[`LICENSE`](LICENSE). The original technical design and build prompt live in\n[`docs/_internal/`](docs/_internal).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericmann%2Fjournal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericmann%2Fjournal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericmann%2Fjournal/lists"}