{"id":47709956,"url":"https://github.com/fluo10/sapphire-journal","last_synced_at":"2026-05-25T01:07:05.351Z","repository":{"id":341930667,"uuid":"1171393412","full_name":"fluo10/sapphire-journal","owner":"fluo10","description":"Markdown-based task and note manager for humans and AI agents — your data lives in plain text, timeless like fossils.","archived":false,"fork":false,"pushed_at":"2026-05-23T02:24:22.000Z","size":5802,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T02:39:01.631Z","etag":null,"topics":["cli","markdown","mcp","note-taking","task-manager"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluo10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-03T07:17:16.000Z","updated_at":"2026-05-23T02:24:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fluo10/sapphire-journal","commit_stats":null,"previous_names":["fluo10/archelon","fluo10/sapphire-journal"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/fluo10/sapphire-journal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluo10%2Fsapphire-journal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluo10%2Fsapphire-journal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluo10%2Fsapphire-journal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluo10%2Fsapphire-journal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluo10","download_url":"https://codeload.github.com/fluo10/sapphire-journal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluo10%2Fsapphire-journal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33453557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","markdown","mcp","note-taking","task-manager"],"created_at":"2026-04-02T18:29:30.348Z","updated_at":"2026-05-25T01:07:05.347Z","avatar_url":"https://github.com/fluo10.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sapphire-journal\n\nMarkdown-based task and note manager for humans and AI agents — your data lives in plain text, timeless like fossils.\n\n## Concept\n\n- **Markdown as source of truth** — all data lives in plain `.md` files you can read and edit with any tool\n- **SQLite as cache** — fast querying and indexing on top of the Markdown files (planned)\n- **Bullet-journal inspired** — tasks, events, and notes are equal peers, each living as its own entry; just as a bullet journal treats every bullet (task, event, or note) uniformly, sapphire-journal treats every entry the same way regardless of type\n- **Text-editor / IDE compatible** — plain `.md` files with YAML frontmatter; readable and editable in any editor without special tooling\n- **Human–AI collaborative editing** — designed to work alongside AI agents (Claude, etc.) that can read, create, and edit entries in the same journal via git or Syncthing sync\n\n## Design decisions\n\n### Entry IDs: caretta-id instead of sequential numbers\n\nEach entry filename is prefixed with a [caretta-id](https://github.com/fluo10/caretta-id) — a 7-character BASE32 identifier with decisecond precision (e.g. `123abcd_my_note.md`).\n\nSequential IDs would collide when a human and an AI agent add entries at the same time in a shared journal synced via git or Syncthing.\ncaretta-id uses the current Unix time in deciseconds as its value, so two entries created more than 0.1 seconds apart are guaranteed to have different IDs — a collision-free guarantee without any central coordinator.\n\n### File layout: `{year}/{id}_{slug}.md`\n\nEntries are grouped into year directories (e.g. `2026/`) to prevent the journal root from filling up over time, while keeping the hierarchy shallow enough to stay navigable.\nThe slug derived from the entry title keeps filenames readable even without opening sapphire-journal.\n\n## Data model\n\nEach file is an **Entry** — the primary unit of data. An entry can contain free-form notes, task checkboxes (`- [ ]`), or both.\n\nA note entry:\n\n```markdown\n---\nid: '1a2b3c4'\ntitle: Meeting notes\ncreated_at: '2026-03-06T14:00:00'\ntags: [work]\n---\n\nDiscussion points from the team meeting.\n```\n\nA task entry adds a `task` block:\n\n```markdown\n---\nid: '2b3c4d5'\ntitle: Fix login bug\ncreated_at: '2026-03-06T10:00:00'\ntags: [work, backend]\ntask:\n  status: open\n  due: '2026-03-08T18:00:00'\n---\n\nReproduction steps and notes here.\n```\n\nAn event entry adds an `event` block:\n\n```markdown\n---\nid: '3c4d5e6'\ntitle: Team sync\ncreated_at: '2026-03-06T09:00:00'\nevent:\n  start: '2026-03-07T15:00:00'\n  end: '2026-03-07T16:00:00'\n---\n```\n\n## Installation\n\n### Linux / macOS\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/fluo10/sapphire-journal/main/install.sh | sh\n```\n\n### Windows\n\n```powershell\nirm https://raw.githubusercontent.com/fluo10/sapphire-journal/main/install.ps1 | iex\n```\n\n### cargo-binstall\n\n```sh\ncargo binstall sapphire-journal-cli\n```\n\n### From source\n\n```sh\ncargo install sapphire-journal-cli\n```\n\n## CLI usage\n\nSee [sapphire-journal-cli/README.md](sapphire-journal-cli/README.md) for the full command reference.\n\nA **journal** is any directory tree that contains a `.sapphire-journal/` directory.\n`sapphire-journal` locates it by walking up from the current directory, the same way `git` finds `.git/`.\nUse `sapphire-journal init` to create one.\n\n## VS Code extension\n\nThe `sapphire-journal-vscode` extension integrates with the editor:\n\n- **Auto-fix on save** — runs `entry fix` automatically, keeping filenames and year directories in sync\n- **Hierarchical tree view** — entries displayed as a parent-child tree with type icons, ThemeIcon status decorations, period filter, and tree/list toggle\n- **Drag-and-drop reparenting** — drag entries in the tree to reassign parent\n- **New Entry**, **New Child Entry**, **Open Entry by ID**, **Remove Entry**, **List Entries** commands available from the Command Palette and context menu\n- **Rich tooltips** — hover over tree items to see full entry details\n\nAvailable on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fluo10.sapphire-journal-vscode) and [Open VSX Registry](https://open-vsx.org/extension/fluo10/sapphire-journal-vscode).\nPlatform-specific VSIX files (with the CLI binary bundled) are also on the [Releases](https://github.com/fluo10/sapphire-journal/releases) page.\n\n## Project structure\n\n```\nsapphire-journal/\n├── sapphire-journal-core/     # Data model, Markdown parser/serializer, SQLite cache\n├── sapphire-journal-cli/      # CLI binary (sapphire-journal)\n├── sapphire-journal-mcp/      # MCP server binary (sapphire-journal-mcp)\n├── sapphire-journal-desktop/  # Desktop GUI (egui)\n└── sapphire-journal-vscode/   # VS Code extension\n```\n\n## Status\n\nEarly development — CLI and MCP server are functional for entry management including hierarchy and full-text search. VS Code extension available on the Marketplace and Open VSX.\n\n## License\n\nThis repository contains components under different licenses:\n\n| Component | License |\n|-----------|---------|\n| `sapphire-journal-core` | MIT OR Apache-2.0 |\n| `sapphire-journal` | MIT OR Apache-2.0 |\n| `sapphire-journal-vscode` | MIT |\n\nSee the `LICENSE` (or `LICENSE-MIT` / `LICENSE-APACHE`) file in each component's directory for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluo10%2Fsapphire-journal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluo10%2Fsapphire-journal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluo10%2Fsapphire-journal/lists"}