| name | x-ipe-tool-ontology |
| description | ⚠️ DEPRECATED — Search functionality migrated to x-ipe-knowledge-extractor-memory. Entity CRUD migrating to x-ipe-knowledge-ontology-builder (FEATURE-059-C). Relationship maintenance migrating to x-ipe-knowledge-ontology-synthesizer (FEATURE-059-D). Use the new knowledge skills instead. |
⚠️ DEPRECATED (FEATURE-059-B)
- Search → Use
x-ipe-knowledge-extractor-memory (scripts/search.py)
- Entity CRUD → Will migrate to
x-ipe-knowledge-ontology-builder (FEATURE-059-C)
- Relationships → Will migrate to
x-ipe-knowledge-ontology-synthesizer (FEATURE-059-D)
- This skill remains functional until all migrations complete.
KB Ontology Tool Skill
Purpose
Provides the runtime engine for the Knowledge Base Ontology system. Manages KnowledgeNode entities, typed relations, dimension taxonomy, graph clustering, and search — all backed by append-only JSONL event sourcing.
Data Storage
| Store | Location | Format |
|---|
| Master entities | x-ipe-docs/knowledge-base/.ontology/_entities.jsonl | Append-only JSONL events |
| Named graphs | x-ipe-docs/knowledge-base/.ontology/{cluster}.jsonl | Derived views (auto-generated) |
| Dimension registry | x-ipe-docs/knowledge-base/.ontology/.dimension-registry.json | JSON taxonomy |
| Graph index | x-ipe-docs/knowledge-base/.ontology/.graph-index.json | Auto-generated manifest of all named graphs |
Available Scripts
All scripts are in .github/skills/x-ipe-tool-ontology/scripts/.
Entity Operations (ontology.py)
| Command | Purpose | Example |
|---|
create | Create KnowledgeNode | python3 ontology.py create --type KnowledgeNode --props '{"label":"JWT Auth","node_type":"concept","source_files":["src/auth.py"]}' --graph PATH |
get | Get entity by ID | python3 ontology.py get --id know_abc123 --graph PATH |
update | Update properties | python3 ontology.py update --id know_abc123 --props '{"weight":8}' --graph PATH |
delete | Delete entity | python3 ontology.py delete --id know_abc123 --graph PATH |
list | List entities | python3 ontology.py list [--type KnowledgeNode] --graph PATH |
query | Filter by properties | python3 ontology.py query --type KnowledgeNode --where '{"node_type":"concept"}' --graph PATH |
relate | Create relation | python3 ontology.py relate --from ID1 --rel depends_on --to ID2 --graph PATH |
related | Get related entities | python3 ontology.py related --id ID [--rel TYPE] [--dir outgoing] --graph PATH |
find-path | BFS shortest path | python3 ontology.py find-path --from ID1 --to ID2 --graph PATH |
validate | Validate constraints | python3 ontology.py validate --graph PATH |
load | Load full graph state | python3 ontology.py load --graph PATH |
retag | Re-tag filed-untagged files | python3 ontology.py retag --scope PATH --ontology-dir PATH --intake-status PATH |
Dimension Registry (dimension_registry.py)
| Command | Purpose | Example |
|---|
resolve | Resolve name/alias | python3 dimension_registry.py resolve --name tech --registry PATH |
register | Register dimension | python3 dimension_registry.py register --dimension '{"name":"technology","type":"multi-value","examples":["Python"]}' --registry PATH |
list | List dimensions | python3 dimension_registry.py list --registry PATH |
rebuild | Rebuild from entities | python3 dimension_registry.py rebuild --entities PATH --registry PATH |
Graph Operations (graph_ops.py)
| Command | Purpose | Example |
|---|
build | Build named graphs | python3 graph_ops.py build --scope PATH --output PATH [--entities PATH] |
prune | Remove stale refs | python3 graph_ops.py prune --entities PATH |
Search (search.py)
| Arguments | Purpose | Example |
|---|
--query --scope --ontology-dir | Search entities | python3 search.py --query "auth" --scope all --ontology-dir PATH [--depth 3] [--page-size 20] [--page 1] |
Three Operations (AI Agent Workflow)
Operation A: Tag (格物→致知)
AI agent reads KB content, discovers dimensions, resolves aliases via dimension registry, and creates entities/relations. The agent orchestrates this operation by:
- Reading source content files
- Analyzing content to identify knowledge concepts
- Calling
dimension_registry.py resolve for each discovered dimension
- Calling
dimension_registry.py register for new dimensions
- Calling
ontology.py create for each entity
- Calling
ontology.py relate for relationships between entities
Operation B: Build Graph
Automated script that builds named graph files from the master entity store. Also generates .graph-index.json — a manifest listing all named graphs with metadata (entity count, dimensions, root entity info).
python3 graph_ops.py build \
--scope x-ipe-docs/knowledge-base/ \
--output x-ipe-docs/knowledge-base/.ontology/ \
--entities x-ipe-docs/knowledge-base/.ontology/_entities.jsonl
Output includes: graph_index field with the generated manifest content.
Operation C: Search
Search across ontology graphs and push results to the KB Graph Viewer UI.
IMPORTANT: This operation has TWO mandatory steps. You MUST execute BOTH steps in sequence. Do NOT skip Step 2.
Step 1 — Run search and save output:
python3 search.py \
--query "authentication" \
--scope all \
--ontology-dir x-ipe-docs/knowledge-base/.ontology/ \
> /tmp/ontology-search-result.json
Step 2 — Push results to KB Graph Viewer UI via callback API:
python3 ui-callback.py \
--results-json /tmp/ontology-search-result.json
BLOCKING: Step 2 MUST always be executed after Step 1. The ui-callback.py script POSTs search results to the internal callback API (/api/internal/ontology/callback), which broadcasts via SocketIO to the KB Graph Viewer frontend. Without Step 2, search results will NOT appear in the UI. The auth token is auto-detected from the running server's instance/.internal_token file — no --token flag needed. Port defaults to 5858 (from .x-ipe.yaml).
Operation D: Retag (Re-tag Filed-Untagged Files)
Re-processes KB files that were moved but failed ontology tagging (status filed-untagged in .intake-status.json). Creates minimal entities and updates status to filed.
python3 ontology.py retag \
--scope x-ipe-docs/knowledge-base/ \
--ontology-dir x-ipe-docs/knowledge-base/.ontology/ \
--intake-status x-ipe-docs/knowledge-base/.intake/.intake-status.json
Entity Model
KnowledgeNode Properties
| Property | Type | Required | Constraints |
|---|
label | string | ✅ | Human-readable name |
node_type | string | ✅ | concept, entity, or document |
description | string | ❌ | Brief summary |
dimensions | object | ❌ | Canonical dimension keys → values |
source_files | string[] | ✅ | Project-root-relative paths |
weight | number | ❌ | 1-10 (default: 5) |
Relation Types
| Type | Acyclic | Description |
|---|
related_to | No | Bidirectional topical overlap |
depends_on | Yes | Understanding dependency |
is_type_of | No | Taxonomy/classification |
part_of | No | Component composition |
described_by | No | Explanatory relation |
Entity ID Format
All IDs follow the pattern know_{uuid_hex[:8]} (e.g., know_a1b2c3d4).
Output Format
All scripts output JSON to stdout. Errors output JSON {"error": "message"} with exit code 1.
Dependencies
Python stdlib only — no external packages required.
References