Install from the command line or in chat¶
An existing Python or Conda environment does not need to be replaced. Choose one of two installation methods: run the commands yourself, or ask a local client in chat. The environment manager is your choice.
Command-line setup · Chat installation
Method 1: Command-line installation¶
Step 1: Choose your Python environment — a new one is optional¶
Choose one situation below. Python 3.11+ is required; 3.12 is a suitable choice for a new environment. Reuse a suitable existing environment, or use Conda directly. Do not create another .venv inside Conda.
A. You already use a Python / project environment
Open your usual terminal, activate your chosen environment as you normally do, then run:
python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
git --version
Confirm Python is 3.11+, sys.executable points to the intended environment, and pip belongs to it. Git is required for installation from GitHub. Then go straight to Step 2.
Do not install into an unfamiliar system Python, Conda base, or an environment running important experiments. pip can change dependencies; choose a separate Conda or venv environment below if the original must be preserved. If only Git is missing, install it from git-scm.com, reopen the terminal, and reactivate the environment.
B. You use Anaconda / Miniconda
On Windows, open Anaconda Prompt or Miniconda Prompt from the Start menu. On macOS / Linux, use the terminal where conda normally works. You do not need a separate Python installation.
List existing environments first:
conda --version
conda env list
To create a dedicated environment: first confirm that hyper-knowledge is not already listed. Run these lines in order, activating only after creation succeeds. Review and accept Conda's package plan when prompted.
conda create -n hyper-knowledge python=3.12 pip git
conda activate hyper-knowledge
python=3.12 selects Python, pip installs the project, and git reads its GitHub source. They belong to this environment, not base.
To reuse an existing environment: skip conda create. Replace research below with the name you chose from conda env list:
conda activate research
For an environment created by path, use conda activate "full environment path". Check version and paths:
python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
git --version
If pip or Git is missing, confirm that the environment may be changed, install them before Step 2, and otherwise skip this command:
conda install pip git
Install Conda dependencies first, then use pip for this project. Do not use pip install --user. The later Skill option --scope user controls Skill discovery, not pip's installation destination.
Your prompt normally shows the active environment name. In a new terminal, run conda activate hyper-knowledge (or your chosen name) again; do not reinstall.
C. No usable environment yet: install Python and use venv
This section is only for starting from scratch. Install Python 3.11+ and Git. On Windows, enable the Python installer option that adds it to PATH, then reopen the terminal.
Check python --version in Windows PowerShell or python3 --version on macOS / Linux. Python must be 3.11+. Check git --version on either system. Skip installing software you already have.
Windows PowerShell: create a user-directory environment and select it only in this terminal. No script execution-policy change is needed.
$hkEnv = Join-Path $env:USERPROFILE ".venvs\hyper-knowledge"
if (Test-Path -LiteralPath $hkEnv) {
throw "Environment already exists. Inspect it before continuing."
}
python -m venv "$hkEnv"
if ($LASTEXITCODE -ne 0) { throw "Environment creation failed." }
$env:PATH = "$(Join-Path $hkEnv 'Scripts');$env:PATH"
python -c "import sys; print(sys.executable)"
macOS / Linux: first check that ~/.venvs/hyper-knowledge does not already exist; activate and inspect an existing one instead of recreating it. For first-time setup, run these lines in order:
python3 -m venv "$HOME/.venvs/hyper-knowledge"
source "$HOME/.venvs/hyper-knowledge/bin/activate"
python -c "import sys; print(sys.executable)"
Stop if environment creation fails. If venv / ensurepip is missing, install the component matching that Python. Keep the environment and base Python in place. Select it again in a new terminal using the instructions further below.
Step 2: Install Hyper-Knowledge in the chosen environment¶
The same commands apply to all three environment choices. Use the terminal where you just activated or selected the environment. Run each line only after the previous one succeeds:
python -m pip install "git+https://github.com/hanxiangmin/Hyper-Knowledge.git"
python -m hyperknowledge --help
The first line downloads the project and dependencies; the second displays help. Continue when you see entries such as parse, bundle, visualize, and skill. python -m pip targets this exact Python environment; hk need not already be recognized.
For Python / Notebook or CLI use, installation is complete. Continue only if you want a Skill in your agent client.
Step 3: Optionally install the Codex or Kimi Code Skill¶
The client application must already be installed and able to sign in. This step installs a Skill, not the client itself. Use the same environment as Step 2.
Codex:
python -m hyperknowledge skill install --platform codex --scope user
Kimi Code:
python -m hyperknowledge skill install --platform kimi --scope user
Run the command for your client, or both if you use both; do not reinstall the runtime. The installer returns status and a path. Inspect local-edit or duplicate warnings instead of automatically adding --force. Start a new client session after success.
Method 2: Chat installation¶
Choose your client and copy its complete request directly into chat:
Codex
Please follow https://github.com/hanxiangmin/Hyper-Knowledge to install the user-level hyper-knowledge Skill for Codex. An existing Python/Conda environment is fine; ask before overwriting local edits.
Kimi Code
Please follow https://github.com/hanxiangmin/Hyper-Knowledge to install the user-level hyper-knowledge Skill for Kimi Code. An existing Python/Conda environment is fine; ask before overwriting local edits.
You do not need to perform the command-line installation first. Repository instructions cover the details; handle any login or approval request yourself. Start a new session after installation. Web chat without local tool access cannot install software on your computer.
What do I do after installation?¶
In Codex, enter $hyper-knowledge; in Kimi Code, enter /skill:hyper-knowledge, then describe your task and provide the file. For example: “Read notes.md and generate a higher-order graph workbench with member roles and source evidence.”
The default route uses the client's model to read the document and local Python to process the result; no second Hyper-Knowledge model key is needed. Independent Python/CLI extraction requires model configuration; structured import and rendering do not.
Python / Notebook · API reference · CLI recipes · Skill usage
What about a new terminal?¶
Conda: open Anaconda Prompt or a Conda-enabled terminal and activate the environment used for installation:
conda activate hyper-knowledge
python -m hyperknowledge --help
Substitute your own environment name if different. For scripts, you can explicitly select the environment without manual activation:
conda run -n hyper-knowledge python -m hyperknowledge --help
conda run -n hyper-knowledge python -m hyperknowledge skill install --platform codex --scope user
Run the second line only to install or update the Skill, not every time you use it. For Kimi, use --platform kimi. For path-based environments, replace conda run -n hyper-knowledge with conda run -p "full environment path".
venv: Windows PowerShell can use the fixed interpreter path without activation:
& "$env:USERPROFILE\.venvs\hyper-knowledge\Scripts\python.exe" -m hyperknowledge --help
macOS / Linux:
source "$HOME/.venvs/hyper-knowledge/bin/activate"
python -m hyperknowledge --help
Other existing environments: activate as usual, check python -c "import sys; print(sys.executable)", then use python -m hyperknowledge.
hk is an installed shortcut, not a built-in command. Use it when the intended environment is active and hk --help works; otherwise use the explicit module invocation above. Do not copy venv's Scripts/python.exe path for Conda. Activation or conda run preserves Conda's environment settings.
Use the same Conda environment in a Notebook¶
Complete runtime installation above, then run in a terminal:
conda activate hyper-knowledge
python -m pip install ipykernel
python -m ipykernel install --user --name hyper-knowledge --display-name "Python (Hyper-Knowledge)"
If reusing another environment, replace the first line's environment name. The remaining commands install/register a kernel, not another Python. If that kernel name already exists, inspect and select it first; do not overwrite a kernel you need to keep. Use a different --name when appropriate.
In Jupyter / VS Code's kernel menu, choose Python (Hyper-Knowledge) and run:
import sys
import hyperknowledge
print(sys.executable)
print(hyperknowledge.__version__)
The interpreter should point to the intended Conda environment. The Notebook server can run elsewhere, but the executing kernel must be correct. Runnable Notebook and embedded workbench
Existing or interrupted installations¶
Do not delete an existing environment or force a Skill overwrite. Inspect from the target environment first:
python -m pip show hyper-knowledge
python -c "import sys; print(sys.executable)"
This shows version, location and interpreter, not every local modification. Inspect and ask before updating editable sources, modified Skills or conflicting copies. Changing the Python environment also requires confirming whether an existing Skill should be rebound; do not silently replace its active runtime.
If the first download is interrupted, reactivate the same environment and retry only Step 2's pip installation. Do not recreate the environment or run conda create again. Resolve a failed step before continuing to Skill installation.
Troubleshooting, if needed¶
| Problem | What to do |
|---|---|
Windows cannot find conda |
Use Anaconda / Miniconda Prompt; do not repeatedly reinstall Python from ordinary PowerShell |
conda activate does not work in this shell |
Use a Conda-enabled terminal or conda run above; do not install into the wrong environment |
| Python too old or pip belongs elsewhere | Select another environment or create an isolated Python 3.12 environment, without upgrading your research environment in place |
git missing |
In Conda, install Git before this project with conda install git, or use system Git |
hk or hyperknowledge missing |
Check that the installation environment is active and Step 2 succeeded |
| Conda commands work but a desktop client reports DLL/library failures | Activation settings may be missing; start the client from the same activated terminal or reproduce with conda run, not by reinstalling into base |
| Notebook import fails but terminal import works | Check Notebook sys.executable and select the correct kernel |
| Local edits or duplicate Skill detected | Inspect the installation rather than adding --force automatically |
Optional diagnostics in the installation environment:
python -m hyperknowledge skill doctor --platform codex --scope user --deep --json
Use --platform kimi for Kimi. This is optional, not Docker; it checks local installation and a synthetic flow, not a complete live-client session.
Instructions for clients performing installation¶
The user only needs the short chat request above. Read this guide, identify their chosen client and environment, and do not silently modify base, system Python or research environments when no environment was specified. Install runtime and Skill using the same retained interpreter; ask before overwriting local edits. Return installation paths, usage and unfinished steps. Do not bypass login or permission requirements.
See Conda environment management, pip in Conda, and conda run. Actual compatibility and test coverage are recorded separately. Unpushed local code is not in the GitHub package; substitute a local wheel in the pip command when testing it.