知识图谱提取

Requires OPENROUTER_API_KEY in environment or .env.mykg (see sample.env.mykg)

uv run pytest -m live -v

Install from PyPI

Install mykg, then run the interactive setup wizard — it asks for your provider, model, and API key and writes mykg_config.yaml and .env.mykg in one step.

pip install mykg
mykg init

Then extract a knowledge graph from your notes:

mykg extract-graph my_notes/

Open mykg_sessions/<timestamp>/output/knowledge_graph.html in your browser to explore the result.

Install from source

Install uv, clone the repo, sync dependencies, run the setup wizard, then extract.

git clone https://github.com/SenolIsci/mykg && cd mykg
uv sync && uv run mykg init --force

Then extract a knowledge graph from your notes:

uv run mykg extract-graph my_notes/

For Ollama (local inference, no API key needed), pull a model and select the ollama-local profile when mykg init prompts you.

ollama pull llama3.3
mykg init
mykg extract-graph my_notes/

source installs: uv run mykg extract-graph <input_dir> [OPTIONS]

```

<input_dir> is any directory containing your source files. Subdirectories are included recursively. Only files matching the configured extensions are copied into the session:

• .md — always included (the pipeline's native format)
• All extensions listed under preprocess.extensions in mykg_config.yaml (.pdf, .docx, .doc, .pptx, .xlsx, .png, .jpg, .jpeg, .html, .htm, .txt by default)

Everything else (.py, .json, .yaml, lock files, etc.) is ignored. Hidden directories (.venv, .git, etc.) and the sessions folder are also excluded automatically, so you can safely point extract-graph at the project root or any parent directory.

Installation

git clone https://github.com/SenolIsci/mykg && cd mykg
uv sync

Ontology-Guided Extraction

- Schema-guided knowledge graph generation — the extracted graph is always grounded in a formal RDFS/OWL schema: concept types, property names, domain/range constraints, and the is-a hierarchy are explicit and inspectable before any entity is extracted - Bring your own ontology — supply a --base-schema TTL file to lock in classes and properties from an existing formal ontology; the LLM expands it with domain-specific concepts but cannot rename, remove, or contradict your authoritative vocabulary - SKOS thesaurus support — pass --thesaurus to load a SKOS vocabulary; skos:exactMatch terms are collapsed silently, skos:closeMatch terms trigger a warning — giving the schema merger richer synonym awareness than string matching alone - Verifiable TTL ontology — after Pass 1, the induced schema is exported as a valid RDFS/OWL Turtle file (intermediate/schema.ttl) that can be opened directly in ontology editors such as Protégé. The TTL is validated by rdflib (syntax + semantic checks: domain/range refer to declared classes, no conflicting ranges) before any extraction begins - Human-in-the-loop ontology design — run with --review to pause after schema induction; inspect and edit schema.json (or load schema.ttl in Protégé, modify, and save back) before a single entity is extracted; resume with mykg approve-schema - Incremental updates — append new files to an existing session, extracting only what changed. Optionally grow the schema from new documents while preserving existing concepts and properties - AI coding assistant friendly — designed for smooth use alongside AI coding assistants such as Claude Code; run extractions, inspect outputs, and iterate on your knowledge graph without leaving your coding environment; see Using mykg with Claude Code - Second brain for AI coding assistants — the Obsidian vault output turns your extracted knowledge graph into a directory of wikilinked Markdown notes that any AI coding assistant can read as project context; point Claude Code, Cursor, or Copilot at output/obsidian_vault/ and ask questions, trace relationships, and get answers grounded in your own documents - MCP server for desktop AI apps — run mykg mcp-serve to expose your knowledge graph via the Model Context Protocol; integrates with Claude Desktop, Cherry Studio, and any MCP-compatible client — 13 query tools let LLMs search entities, explore relationships, find paths, traverse the graph, and read wiki notes directly from your extracted knowledge; see MCP Server <p align="center"> <img src="https://gcore.jsdelivr.net/gh/SenolIsci/mykg@main/docs/diagrams/architecture-sketch.png" width="95%" style="vertical-align:middle;"> </p>

Quick Start

Requires Python 3.11+ (developed on macOS; automated CI runs the test suite on Linux/Ubuntu — Windows is not actively tested), and one of: an Anthropic/OpenAI/OpenRouter API key, Ollama running locally, or the claude CLI.

Articles & Tutorials

Walkthroughs and case studies on Medium:

• How I Turned My Website Into a Knowledge Graph with myKG
• How to Build a Second Brain You Can Actually Trust
• Build an LLM Wiki for Your AI Agents
• From Documents to a Living Knowledge Graph: Introducing myKG

Examples

```bash

Example

mykg merge-graphs 2026-05-01T10-00-00 2026-05-15T14-30-00

Configuration

All configuration lives in a single mykg_config.yaml file discovered automatically from the working directory (or any parent). There are no hardcoded defaults in the code — the YAML is the sole source of truth.

mykg init           # interactive: choose provider, model, paste API key
                    # writes mykg_config.yaml and .env.mykg in one step
mykg init --force   # overwrite an existing config
mykg init --profile openrouter-free --model google/llama-4-maverick --api-key sk-or-...  # non-interactive

The wizard walks you through three prompts:

1. Profile — choose your LLM provider (OpenRouter, Anthropic, OpenAI, Ollama, Claude CLI, or Agent / Claude Code skill)
2. Model — accept the default or type any model slug for that provider (skipped in agent mode — the host Claude Code session is the LLM)
3. API key — paste your key (skipped for Ollama, Claude CLI, and agent mode)

.env.mykg

ANTHROPIC_API_KEY=sk-ant-... ``` For source installs you can also copy sample.env.mykg to .env.mykg as a starting template.

Options

Advanced Options

Shallow-clone a GitHub repo (git clone --depth 1, no Crawlee/venv)

mykg fetch-web https://github.com/SenolIsci/mykg mykg extract-graph ./mykg_web_fetch/github.com_SenolIsci_mykg/input/

Hitting API Rate Limits (HTTP 429)

If you see repeated 429 errors during pass1, pass2, or the orphan-connection pass, your account's requests-per-minute limit is lower than the number of concurrent calls mykg is making. Each profile sets these independently under pipeline::

• pass1.max_workers — concurrent schema-induction batch calls
• pass2.max_workers — concurrent per-file extraction calls
• orphan_pass.max_workers — concurrent orphan-connection calls

Lower these (e.g. from 8 down to 2–4) in the active profile to reduce concurrent requests. This is especially likely on openrouter-free (free-tier models have very low per-minute caps) and on lower-tier anthropic-claude/openai accounts. llm.retry_429_max / llm.retry_429_base_delay control automatic backoff on a 429, but per Invariant 13 a persistent 429 is a signal to reduce max_workers, not just retry harder. claude-cli and agent-claude-code are unaffected — both are serial by design (max_workers: 1).

API Keys

myKG reads API keys from environment variables. Set them by exporting directly or by creating a .env.mykg file in your project directory (loaded automatically on startup).

Option A — export in your shell:

export ANTHROPIC_API_KEY=sk-ant-...

Option B — create a .env.mykg file:

```bash

claude-cli profile

myKG ships with a claude-cli profile that runs extractions through the locally-installed claude CLI.

Setup

Install the claude CLI, then install mykg and run the setup wizard — select [5] Claude CLI when prompted.

npm install -g @anthropic-ai/claude-code
pip install mykg && mykg init
mykg extract-graph my_notes/

How it works

The claude-cli provider calls claude -p as a subprocess for every LLM step (Pass 1 schema induction, Pass 2 extraction, orphan connection, name normalization). All pipeline features — session isolation, resumability, orphan recovery, cross-session merge — work identically to API-based providers.

Key constraints of the claude-cli profile: - max_workers must be 1 — the claude CLI is serial by design; parallel workers will queue - The effort and model fields in mykg_config.yaml map directly to --effort and --model flags passed to claude -p

Using myKG from inside Claude Code Session

You can run myKG extractions as a tool call from within a Claude Code session. This is useful for building knowledge graphs from notes or documentation while you work:

```bash

Then reference the output in your session:

All non-live tests (fast, no API key needed)

uv run pytest -m "not live" -v

All tests including live API integration tests

Extract Pipeline

Reads a directory of mixed format files and produces a typed knowledge graph in three output formats. The pipeline runs 12 sequential steps; all intermediate state is persisted so any step can be re-entered without repeating upstream work.

Pipeline Steps

The pipeline runs 12 steps in sequence. All intermediate state is written to disk so any step can be re-entered without repeating upstream work.

Pass 1 internally runs four sequential stages: parallel batch induction → algorithmic merge → harmonization LLM call → quality review LLM call.

→ pipeline halts; edit mykg_sessions/<name>/intermediate/schema.json

mykg approve-schema --session <name> mykg extract-graph my_notes/ --session <name> --review # resumes from Pass 2 ```