Quartz 5

index

6 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 or any messenger. Voice input is handled client-side via STT (e.g. FUTO Keyboard on Android, Whisper on desktop, Web Speech API in browsers). 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 /             │
                │  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/
    └── config.toml, plugins/  ← Quartz publishing configuration

The structure is intentionally simple and can evolve over time.

See Quartz configuration for available options and Quartz features for what the published site supports.

See Conventions 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 or any messenger. Voice input is handled client-side via STT (e.g. FUTO Keyboard on Android, Whisper on desktop, Web Speech API in browsers).

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.

Quartz supports wikilinks, graph view, full-text search, LaTeX, syntax highlighting, and more — see the Quartz documentation for available features and the authoring guide for Markdown syntax.

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.)

Connect from Kai

Kai is a cross-platform open-source AI assistant that supports MCP servers and multiple LLM providers.

LLM Backend

Kai can use the same local Ollama instance as the rest of the Gitlas stack, so all interfaces share one model and consistent behavior.

  1. In Kai, go to Settings > Add Service > OpenAI-Compatible API
  2. Set Base URL to http://<ollama-host>:11434/v1 (e.g. http://localhost:11434/v1 or http://ollama:11434/v1 on the same Docker network)
  3. Kai fetches the model list automatically — select your preferred model (e.g. qwen2.5:3b for CPU, qwen2.5:7b for GPU)
  4. Reorder services so the local instance is first (primary) in the fallback chain

Kai also supports 29 providers with automatic fallback — the local Ollama instance is tried first, with an optional cloud provider as fallback.

MCP Servers

All 7 Gitlas tools are exposed as MCP tools in Kai’s tool palette:

  1. Run make demo-minimal (or make demo for the full stack)
  2. In Kai, go to Settings > Tools > Add MCP Server
  3. Enter the URL: http://<gitlas-host>:8765/sse

Available tools: read_page, search_documents, create_page, update_page, create_branch, commit_changes, push_changes.

Add forgejo-mcp at http://<forgejo-host>:8080/sse for PR, issue, and release management.

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

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.

Further Reading

Graph View