Quartz 5

README

4 min read

Gitlas logo

Gitlas

A Git-native knowledge atlas for work, life and family.

Gitlas is a simple idea:

Git is the single source of truth.

All knowledge is stored as plain Markdown files in a Git repository. An AI agent is the primary interface — accessed through chat, voice messages, or any messenger. Quartz provides a read-only web view. Any text editor or IDE remains available as a direct fallback.

Everything else is replaceable:

  • Forgejo for collaboration
  • Quartz for publishing
  • Ollama for local inference
  • any messenger or chat UI for the agent interface

No proprietary formats. No database lock-in. No SaaS dependency.

Principles

Git First

Every piece of information lives in Git.

Markdown
    ↓
   Git
    ↓
Gitlas

All changes are:

  • versioned
  • auditable
  • reviewable
  • reversible

Human Readable

Knowledge remains accessible without any application.

/work/projects/project-a.md
/personal/travel/japan-2027.md
/family/house/heat-pump.md

Quartz publishes a read-only web view for browsers. A text editor or IDE is always available as a direct fallback.

AI as a Layer

AI is not the source of truth.

AI:

  • reads content
  • summarizes content
  • creates content
  • updates content

Git stores the final result.

User
  ↓
Agent
  ↓
Markdown
  ↓
Git

Fully Self Hosted

Gitlas can run entirely on your own infrastructure.

Suggested stack:

Forgejo
Git
Quartz
Ollama
Agent UI (any messenger / chat)

No cloud required.

Architecture

                ┌─────────────────────┐
                │   Agent Interface   │
                │ (chat / voice /     │
                │  any messenger)     │
                └──────────┬──────────┘
                           │
                           ▼
                      Ollama LLM
                           │
                           ▼
                       Gitlas
                           │
                           ▼
                       Forgejo
                           │
                           ▼
                      Git + Markdown
                           │
                    ┌──────┴──────┐
                    ▼             ▼
                Quartz         Editors
              (read-only)    (emergency)

Repository Structure

gitlas/
│
├── work/
│   ├── projects/
│   ├── architecture/
│   └── knowledge/
│
├── personal/
│   ├── finances/
│   ├── travel/
│   └── health/
│
├── family/
│   ├── house/
│   ├── documents/
│   ├── insurance/
│   └── planning/
│
├── templates/
│
├── attachments/
│
├── secrets/
│
└── quartz/

The structure is intentionally simple and can evolve over time.

See CONVENTIONS.md for naming, frontmatter schema, template usage, attachment handling, and commit message conventions.

Access Patterns

Primary — Agent Interface

Everyday access through an always-on AI assistant. The agent reads, writes, and searches the knowledge base via natural language — chat, voice messages, or any messenger.

User Request
      ↓
  Agent
      ↓
  Markdown
      ↓
   Git

Examples:

Create a page for our summer vacation 2027.

Summarize all insurance contracts.

Find information about the heat pump.

Update the Wi-Fi credentials.

Read Fallback — Quartz

If the agent is unreachable, the knowledge base is still fully readable through Quartz’s published web view. No agent, no editor, no login required — any browser suffices.

Examples:

  • family members browsing insurance pages
  • project stakeholders reviewing documentation
  • guests reading shared travel plans

Emergency Fallback — Direct Edit

If both agent and Quartz are offline, any text editor or IDE can read and edit Markdown files directly. Git remains the source of truth — no tool can circumvent versioning.

Examples:

  • vim family/house/heat-pump.md
  • VS Code with the repository folder open
  • Obsidian pointing at the Git working tree

AI Workflow

Read

User Question
      ↓
 Agent
      ↓
 Markdown Search
      ↓
 Response

Write

User Request
      ↓
 Agent
      ↓
 Markdown Update
      ↓
 Git Commit
      ↓
 Push

Review Mode

Recommended for shared repositories.

User Request
      ↓
 Agent
      ↓
 Branch
      ↓
 Pull Request
      ↓
 Review
      ↓
 Merge

Agent Interface

The AI does not run raw shell commands. It acts through a small, well-defined set of operations (for example, via an MCP server backed by the Forgejo API):

  • read_page, search_documents
  • create_page, update_page
  • create_branch, commit_changes, push_changes

(Forgejo operations like PRs, issues, releases are handled by a separate forgejo-mcp server — see docker-compose.yml profiles demo (gitlas + ollama) and full (adds forgejo-mcp, ollamarama, open-webui, quartz). forgejo-mcp is an upstream image at codeberg.org/goern/forgejo-mcp:latest.)

For a discussion of multi-user collaboration and how jj (Jujutsu) can reduce merge friction between concurrent AI agents, see COLLABORATION.md.

Why Gitlas?

Because knowledge should be:

  • open
  • portable
  • searchable
  • durable
  • self-hosted
  • AI-assisted
  • human-readable

And because Git is already very good at preserving history.

Vision

Gitlas aims to become a personal and collaborative knowledge atlas where:

  • Markdown is the format
  • Git is the truth
  • An AI agent is the interface
  • Quartz is the read-only window
  • Any editor is the emergency fallback

Everything else is optional.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Gitlas is currently a lightweight reference and template repository. If it later evolves into a standalone hosted product or platform, a move to AGPLv3 may be considered for that component.

Graph View