Skip to content

getting-started.md

Latest commit

 

History

History
188 lines (132 loc) · 6.24 KB

getting-started.md

File metadata and controls

188 lines (132 loc) · 6.24 KB
Raw

Getting Started with Pyrite

Pyrite is a Knowledge-as-Code platform. You keep structured knowledge in markdown files with YAML frontmatter, validated against schemas, versioned in git, and searchable by any AI through MCP. This tutorial walks you from zero to a working knowledge base in about five minutes.

Install Pyrite

No PyPI wheel yet — install from source:

git clone https://github.com/markramm/pyrite.git && cd pyrite
pip install -e ".[all]"   # Core + AI + semantic search + dev tools

Or run the bundled Docker image instead (docker compose up -d, serves on http://localhost:8088) — see the README for details, or pyrite.wiki for hosted/one-click cloud options.

Create Your First Knowledge Base

pyrite init --template research --path my-research
cd my-research

This creates:

  • kb.yaml — your KB configuration: name, entry types, field schemas
  • Template subdirectories (e.g. people/, organizations/, events/, notes/) for the research template

The SQLite search index lives outside the KB directory, at ~/.pyrite/index.db — it's derived from your files and rebuildable anytime (pyrite index build), so it's fine to leave out of version control.

pyrite init does not run git init for you. If you want every change versioned from the start (recommended for a git-native product), initialize git yourself:

cd my-research && git init && git add -A && git commit -m "Initial KB"

Templates available: research, software, zettelkasten, intellectual-biography, movement, empty.

Your knowledge base is just a directory of markdown files. You can open them in any editor.

Create Some Entries

Let's add a few entries to build up some content.

A person:

pyrite create -k my-research --type person --title "Ada Lovelace" \
  --body "Mathematician and writer. Wrote the first algorithm intended for a machine." \
  --tags "mathematics,computing"

A note:

pyrite create -k my-research --type note --title "Knowledge management principles" \
  --body "Atomic notes. Link liberally. Let structure emerge from connections, not folders."

An event:

pyrite create -k my-research --type event --title "Analytical Engine demonstration" \
  --body "Charles Babbage presented the design of the Analytical Engine." \
  --date "1837-01-01"

A note with tags:

pyrite create -k my-research --type note --title "Use markdown for all entries" \
  --body "Plain text is portable, diffable, and future-proof. Markdown adds just enough structure." \
  --tags "process"

Each command creates a markdown file with YAML frontmatter like this:

---
id: ada-lovelace
title: Ada Lovelace
type: person
tags: [mathematics, computing]
created: 2026-03-03T10:00:00
---

Mathematician and writer. Wrote the first algorithm intended for a machine.

The id is auto-generated from the title. Pyrite validates fields against the type schema on every write.

Search Your Knowledge Base

Keyword search works out of the box:

pyrite search "algorithm" -k my-research
pyrite search "mathematics" -k my-research --type person

Semantic search finds conceptually related content, not just keyword matches. It uses a local embedding model (all-MiniLM-L6-v2, ~90 MB) that is downloaded the first time it is needed — expect the first semantic search or the first pyrite-server write to take a minute, once. Set PYRITE_AUTO_EMBED=0 to skip embedding on write and keep keyword search only:

pyrite search "early computer science pioneers" -k my-research --mode semantic

Hybrid mode combines both:

pyrite search "computing history" -k my-research --mode hybrid

Connect an AI via MCP

Pyrite includes a built-in MCP server.

One-command setup for Claude Desktop/Code:

pyrite mcp-setup

This writes the mcpServers entry directly into ~/.claude/claude_desktop_config.json (or pass --config for a different path) — no manual JSON editing needed. Restart Claude Desktop/Code afterward to pick up the change.

Manual setup (any MCP-compatible client): add this to your config:

{
  "mcpServers": {
    "pyrite": {
      "command": "/absolute/path/to/.venv/bin/pyrite",
      "args": ["mcp"]
    }
  }
}

Your AI can now search, read, and create entries in your knowledge base. It gets 29 read tools, 11 write tools, and 8 admin tools across three permission tiers. For read-only access:

{
  "mcpServers": {
    "pyrite": {
      "command": "/absolute/path/to/.venv/bin/pyrite",
      "args": ["mcp", "--tier", "read"]
    }
  }
}

See also: Gemini MCP integration | OpenAI MCP integration

Use Templates for Domain-Specific KBs

Templates install extensions with specialized entry types and tools tailored to a domain:

pyrite init --template software --path my-project

The software template adds ADRs, components, backlog items, standards, and runbooks — everything you need to manage a software project's knowledge. Other templates include:

  • zettelkasten — note maturity workflows (capture, elaborate, question, refine, connect)
  • encyclopedia — articles with review and voting workflows
  • cascade — timeline research with actors and capture lanes

Launch the Web UI

Pyrite ships an optional web interface for browsing, editing, and visualizing your knowledge base. If you installed with the server extra (included in [all]):

pyrite serve

Visit http://localhost:8088. The web UI includes a markdown editor with wikilink autocomplete, an interactive knowledge graph, collections with kanban/table/gallery views, and an AI chat sidebar.

Next Steps