DeepRefine-Skill

██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗   ██╗███████╗
██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗  ██║██╔════╝
██║  ██║█████╗  █████╗  ██████╔╝██████╔╝█████╗  █████╗  ██║██╔██╗ ██║█████╗
██║  ██║██╔══╝  ██╔══╝  ██╔═══╝ ██╔══██╗██╔══╝  ██╔══╝  ██║██║╚██╗██║██╔══╝
██████╔╝███████╗███████╗██║     ██║  ██║███████╗██║     ██║██║ ╚████║███████╗
╚═════╝ ╚══════╝╚══════╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝

DeepRefine-Skill plugs into agent workflows and use a single command /deeprefine in your agent CLI to refine and evolve your LLM-Wiki (e.g., graphify) knowledge base.

It refines your graphify knowledge graph for better future retrieval and Q&A quality.

Supported agent frameworks:

News

[2026/6/18] unreleased - Gemini CLI supported.
[2026/6/17] unreleased - Added dry-run-first refinement, evidence-aware action review, ambiguous-node warnings, and LOW-confidence apply guard.
[2026/6/15] v0.1.8 - Aligned interaction memory with LLM-Wiki (graphify) and fixed the single query refinement issue.
[2026/6/2] v0.1.7 — Cursor skill + deeprefine refine with configurable API. And strict DeepRefine agent loop.

Agent CLI (Recommended)

This is the default mode and the main workflow for this project.

One-time setup

pip install deeprefine-cli graphifyy

cd /path/to/your-kb-project
graphify cursor install

# for Cursor
deeprefine cursor install
# for Copilot CLI
deeprefine copilot install
# for Gemini CLI
deeprefine gemini install # or deeprefine gemini link

After upgrading the package, run the command again to refresh local skill files.

Typical session (Agent CLI)

/graphify .
/graphify ./ --wiki
/graphify query "your question 1"
/graphify query "your question 2"
# ..
/deeprefine

What `/deeprefine` does now (default queue behavior)

Procedures:

When you run /deeprefine, it should follow this order:

deeprefine history sync-memory
- import queries from graphify-out/memory/query_*.md
- write to graphify-out/.deeprefine/history.jsonl
load pending queries from history.jsonl (refined != true)
refine pending queries sequentially
for refinement-path queries, generate <refinement> actions and run deeprefine review
stop in dry-run mode and show the review report; do not modify graph.json yet
only after user approval, run deeprefine apply and then deeprefine loop finish

Agent artifacts

graphify-out/
├── graph.json                              # graphify main graph; unchanged until apply approval
├── memory/
│   └── query_*.md                          # graphify query logs (sync source)
└── .deeprefine/
    ├── history.jsonl                       # DeepRefine-maintained history queue
    ├── graph.json.bak                      # backup before first apply in this run
    ├── loop_trace_<query_id>.json          # per-query loop audit trace
    ├── refinement_results_<YYYYMMDD>.jsonl # per-day run log
    ├── refinement_actions_*.txt            # optional; only when refinement path is taken
    ├── proposed_refinement_actions_*.txt    # CLI dry-run proposed actions
    ├── proposed_refinement_review_*.md      # evidence-aware review report
    └── proposed_refinement_review_*.json    # optional structured review report

Agent-related commands

Run from your KB project root.

Command	Description
`deeprefine cursor install`	Install `/deeprefine` skill for Cursor (`.cursor/skills/deeprefine/`)
`deeprefine cursor install --user`	Install Cursor skill for all projects (`~/.cursor/skills/`)
`deeprefine copilot install`	Install `/deeprefine` skill for Copilot CLI (`.github/skills/deeprefine/`)
`deeprefine copilot install --user`	Install Copilot CLI skill for all projects (`~/.copilot/skills/`)
`deeprefine copilot uninstall`	Remove Copilot CLI skill
`deeprefine gemini path`	Print the extension root used for Gemini CLI
`deeprefine gemini link`	Link the current source checkout with `gemini extensions link`
`deeprefine gemini install`	Install the bundled extension with `gemini extensions install`
`deeprefine gemini install --copy-only`	Manual fallback copy to `~/.gemini/extensions/deeprefine-skill`
`deeprefine gemini uninstall`	Remove the extension with Gemini CLI's manager
`deeprefine history sync-memory`	Import `graphify-out/memory/query_*.md` into DeepRefine history
`deeprefine history list --pending`	Show unrefined queue
`deeprefine loop init --query "..."`	Create `loop_trace_<id>.json` template
`deeprefine loop validate --trace-file T`	Validate trace against Reafiner control flow
`deeprefine review --trace-file T --refinement-file F`	Review proposed actions with HIGH/MEDIUM/LOW evidence labels; no graph write
`deeprefine apply --trace-file T --refinement-file F`	Apply `<refinement>` actions to `graph.json` after approval; refuses LOW by default
`deeprefine apply --allow-low-confidence --trace-file T --refinement-file F`	Override LOW-confidence guard explicitly
`deeprefine loop finish --trace-file T [--refinement-file F]`	Persist results and mark history refined

Evidence-aware review and safe apply

/deeprefine should default to dry-run-first behavior. Proposed actions are reviewed before they can modify graphify-out/graph.json. Each action is labeled:

Label	Meaning
`HIGH`	Direct graph or code evidence exists.
`MEDIUM`	k-hop context supports the action, but direct code or exact-edge evidence is missing.
`LOW`	Node names are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`.

Bare function names such as main(), run(), train(), test(), and setup() are treated as ambiguous. Prefer file-qualified names:

BAD:  insert_edge("main()", "calls", "Trainer")
GOOD: insert_edge("pretraining/pretraining_CLIP_fine-grained.py::main()", "calls", "Trainer")

deeprefine apply refuses LOW-confidence actions by default. Use --allow-low-confidence only when the user explicitly accepts the risk.

Copilot CLI Integration

Setup, commands, and session usage

DeepRefine works as a GitHub Copilot CLI agent skill. The skill file is installed into .github/skills/deeprefine/SKILL.md and auto-discovered by Copilot. Shell commands are pre-approved via allowed-tools: shell.

One-time setup

cd /path/to/your-kb-project
pip install deeprefine-cli
deeprefine copilot install --project

After upgrading the package, run deeprefine copilot install --project again to refresh the local skill file. Start a Copilot CLI session and reload:

/skills reload
/skills info deeprefine

Mode detection

Copilot CLI does not natively support sub-commands, so the skill uses keyword-based mode detection in the SKILL.md preamble:

Mode	Trigger keywords	Behavior
Full workflow	`/deeprefine`, "refine", "improve", "fix"	Full Reafiner loop; stops after dry-run review; asks for approval
Review only	"review", "check", "audit", "inspect", "dry-run"	Reads trace + refinement file; shows HIGH/MEDIUM/LOW report; no graph writes
Apply only	"approve", "apply", "write", "go ahead"	Runs `deeprefine apply` only after a prior review; requires explicit user approval in the current message

Copilot CLI session

/deeprefine

The agent runs the full Reafiner loop for all pending queries. For refinement-path queries, it stops after the dry-run review and asks:

[HIGH] insert_edge("trainer.py::train_epoch()", "calls", "validate()")
Evidence: Direct code evidence in trainer.py.
[MEDIUM] insert_edge("data.py::load()", "imports", "torch")
Warning: No direct code evidence found.

Apply only after review. Approve?

Reply "apply" or "go ahead" to proceed; the agent will run deeprefine apply in the follow-up turn.

Gemini CLI Integration

Setup, commands, and session usage

DeepRefine can also be used as a Gemini CLI extension. This keeps the same safe, dry-run-first DeepRefine workflow while making /deeprefine available inside Gemini CLI.

One-time setup for local development

cd /path/to/DeepRefine-Skill
pip install -e .
deeprefine gemini link

deeprefine gemini link calls Gemini CLI's official extension manager:

gemini extensions link /path/to/DeepRefine-Skill

Restart Gemini CLI after linking. Then check:

/extensions list
/commands list

Expected commands:

/deeprefine
/deeprefine:review
/deeprefine:apply

Gemini CLI commands

Command	Description
`deeprefine gemini path`	Print the extension root used for Gemini CLI
`deeprefine gemini link`	Link the current source checkout with `gemini extensions link`
`deeprefine gemini install`	Install the bundled extension with `gemini extensions install`
`deeprefine gemini install --copy-only`	Manual fallback copy to `~/.gemini/extensions/deeprefine-skill`
`deeprefine gemini uninstall`	Remove the extension with Gemini CLI's manager

For normal source development, prefer deeprefine gemini link. It makes the extension visible to /extensions list, whereas copying files alone may not register the extension in newer Gemini CLI versions.

Gemini CLI session

gemini

Then run:

/deeprefine
/deeprefine:review "Why is the graph missing the data loading path?"
/deeprefine:apply "Apply the approved refinement actions from the valid trace."

The extension files are located at the repository root and are also bundled under deeprefine_skill/gemini_extension/ for wheel installs. See docs/gemini-cli.md for details.

Terminal CLI (FAISS + API/vLLM)

Requirements, environment, workflow, and commands

Use this section when you want a pure terminal workflow without Cursor /deeprefine.

Extra requirements

DeepRefine repository installed in atlastune
Inference backend configured (API or vLLM)

conda activate atlastune
cd /path/to/DeepRefine && pip install -e .
pip install deeprefine-cli

# Optional, if DeepRefine repo is elsewhere
export DEEPREFINE_REPO=/path/to/DeepRefine

Inference environment (CLI mode)

Variable	Default
`DEEPREFINE_LLM_URL`	(empty; SDK default)
`DEEPREFINE_EMBED_URL`	(empty; SDK default)
`DEEPREFINE_API_KEY`	fallback to `OPENAI_API_KEY`
`DEEPREFINE_LLM_API_KEY`	fallback to `DEEPREFINE_API_KEY`
`DEEPREFINE_EMBED_API_KEY`	fallback to `DEEPREFINE_API_KEY`
`DEEPREFINE_MODEL`	`gpt-4.1-mini`
`DEEPREFINE_EMBED_MODEL`	`text-embedding-3-small`

Terminal workflow

cd /path/to/your-kb-project

# Option A: import from graphify memory first (recommended)
deeprefine history sync-memory
deeprefine history list --pending
deeprefine refine          # dry-run: proposed actions + review, no graph write
deeprefine refine --apply  # optional: write accepted CLI refine changes

# Option B: add one explicit query
deeprefine history add --query "your question"
deeprefine refine          # dry-run by default

Terminal commands

Command	Description
`deeprefine history add --query "..."`	Append one query to history
`deeprefine history list`	List all history rows
`deeprefine history sync-memory`	Import graphify memory queries into history
`deeprefine history list --pending`	List only unrefined queries
`deeprefine refine`	Generate proposed actions for all pending queries; dry-run by default
`deeprefine refine --query "..."`	Generate proposed actions for a single query; dry-run by default
`deeprefine refine --apply`	Persist accepted CLI refine changes to `graph.json`
`deeprefine refine --rebuild-index`	Rebuild FAISS before refine
`deeprefine index --rebuild`	Rebuild FAISS cache only

Installation

Method	Command
PyPI	`pip install deeprefine-cli==0.1.8`
Source	`pip install -e /path/to/DeepRefine-Skill`

deeprefine --help
# Expect: cursor, copilot, gemini, history, index, refine, review, apply, loop

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
assets		assets
commands		commands
deeprefine_skill		deeprefine_skill
docs		docs
scripts		scripts
skills/deeprefine		skills/deeprefine
.gitignore		.gitignore
GEMINI.md		GEMINI.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SKILL.md		SKILL.md
gemini-extension.json		gemini-extension.json
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

DeepRefine-Skill

News

Agent CLI (Recommended)

One-time setup

Typical session (Agent CLI)

What `/deeprefine` does now (default queue behavior)

Agent artifacts

Agent-related commands

Evidence-aware review and safe apply

Copilot CLI Integration

One-time setup

Mode detection

Copilot CLI session

Gemini CLI Integration

One-time setup for local development

Gemini CLI commands

Gemini CLI session

Terminal CLI (FAISS + API/vLLM)

Extra requirements

Inference environment (CLI mode)

Terminal workflow

Terminal commands

Installation

License

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

DeepRefine-Skill

News

Agent CLI (Recommended)

One-time setup

Typical session (Agent CLI)

What /deeprefine does now (default queue behavior)

Agent artifacts

Agent-related commands

Evidence-aware review and safe apply

Copilot CLI Integration

One-time setup

Mode detection

Copilot CLI session

Gemini CLI Integration

One-time setup for local development

Gemini CLI commands

Gemini CLI session

Terminal CLI (FAISS + API/vLLM)

Extra requirements

Inference environment (CLI mode)

Terminal workflow

Terminal commands

Installation

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

What `/deeprefine` does now (default queue behavior)

Packages