知识图谱提取

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.

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

• 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
• 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
• Resumable pipeline — every stage persists intermediate state; re-enter at any step after a crash or edit
• Session isolation — each run is fully self-contained; inputs, intermediate state, outputs, and logs co-located
• Cross-session merge — combine two independently-produced graphs into one unified knowledge graph
• Bring your own ontology — supply a --base-schema TTL file (RDFS or OWL) to lock in classes and properties from an existing formal ontology; the LLM expands it with domain-specific concepts but will not rename, remove, or contradict your authoritative vocabulary. Please note that this mechanism is controlled by the LLM, and may not be strictly enforced. Add --freeze-schema to skip LLM schema induction entirely and extract from the documents strictly against your ontology verbatim — no surprise types, no invented properties
• 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 — pause after schema induction with --review, edit the schema, and resume extraction. Edit schema.json directly or refine schema.ttl in Protégé and feed it back with --freeze-schema

<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 Ubuntu and Windows), and one of: an Anthropic/OpenAI/Gemini/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, Gemini, 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

Run once against a different profile/model without editing mykg_config.yaml

mykg extract-graph my_notes/ --profile openrouter-free --model google/llama-4-maverick

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/

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

Hitting API Rate Limits (HTTP 429)

A 429 surfaces in the log as a retry warning like:

[WARNING] mykg.llm.retry — OpenAI 429 rate-limit (attempt 1/5) — retrying in 2.0s

429 is a "Too Many Requests" error. 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), on gemini with a free-tier key (5 requests/minute/model — drop pass1/pass2/orphan_pass to 1–2), and on lower-tier anthropic-claude/openai accounts. llm.retry_429_max / llm.retry_429_base_delay control automatic backoff on a 429, but a persistent 429 is a signal to reduce max_workers, not just retry harder. claude-cli is unaffected — it is serial by design (max_workers: 1); it doesn't hit API rate limits since there's no API call. agent-claude-code is not API rate-limited either (no API key involved), but it is not serial — its default profile sets pass1/pass2/orphan_pass max_workers > 1 (configurable, like any other profile), since the skill dispatches multiple subagents per wave.

Also check your quota/credits. Some providers return 429 when your account has exhausted its token quota or spending balance, not only for request cadence. If lowering max_workers doesn't help and the 429s persist from the very first call, check that your account still has available tokens/credits (e.g. the OpenAI/Anthropic billing dashboard, or your OpenRouter balance). No max_workers value will clear a 429 caused by a depleted balance — top up or switch to a profile with quota (e.g. ollama-local for local inference, or claude-cli which bills via your Claude Pro/Max plan instead of the API).

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. pass1.max_schema_proposals (default 50) caps the number of batches dispatched to the LLM; set to -1 to dispatch all batches on large corpora.

→ 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 ```

Troubleshooting